/ Hex Artifact Content
Login

Artifact 9399b09de527be1d055411d7b826125f8f816bb9ebb052de847969bd8c46d701:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c  ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a  ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66  .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53  _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f   file.  ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72  us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20  s might include 
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70  nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76  lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65  erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20  atch the macros 
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72  in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72  , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69  e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d  cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68  piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20  ing library and 
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a  header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28  <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51  ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65  ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30  ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c  BER].  ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20  rocessor macro. 
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74   Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73  e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f  ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67  py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74  amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61  he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68  racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20  e hash might be 
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b  different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1e00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1e10: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1e20: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1e30: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1e40: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1e50: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1e60: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1e70: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1e80: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1e90: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1ea0: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1eb0: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1ec0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1ed0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1ee0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1ef0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1f00: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1f10: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1f20: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1f30: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1f40: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1f50: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1f60: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1f70: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1f80: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1f90: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1fa0: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1fb0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1fc0: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1fd0: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1fe0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1ff0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
2000: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
2010: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
2020: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
2030: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
2040: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
2050: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
2060: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
2070: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
2080: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
2090: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
20a0: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
20b0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
20c0: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
20d0: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
20e0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
20f0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
2100: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
2110: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
2120: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
2130: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2140: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2150: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2160: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2170: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
2180: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
2190: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
21a0: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
21b0: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
21c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
21d0: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
21e0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
21f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2200: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
2210: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
2220: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
2230: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2240: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2250: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2260: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
2290: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
22a0: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
22b0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
22c0: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
22d0: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
22e0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
22f0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
2300: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
2310: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
2320: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
2330: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2340: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2350: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2360: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2370: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
2380: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
2390: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
23a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
23b0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
23c0: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
23d0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
23e0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
23f0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
2400: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
2410: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
2420: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2430: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2440: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2450: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2460: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2470: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2480: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2490: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
24a0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
24b0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
24c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
24d0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
24e0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
24f0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
2500: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2510: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
2520: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2530: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2540: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2550: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2560: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2570: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2580: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2590: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
25a0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
25b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
25c0: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
25d0: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
25e0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
25f0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
2600: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
2610: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
2620: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
2630: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2640: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2650: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2660: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2670: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2680: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2690: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
26a0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
26b0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
26c0: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
26d0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
26e0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
26f0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
2700: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
2710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2730: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2740: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2750: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2760: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2770: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2780: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2790: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
27a0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
27b0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
27c0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
27d0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
27e0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
27f0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
2800: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2810: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
2820: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
2830: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2840: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2850: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2860: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2870: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2880: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2890: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
28a0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
28b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
28c0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
28d0: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
28e0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
28f0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
2900: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
2910: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2920: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
2930: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2940: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2950: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2960: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2970: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2980: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2990: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
29a0: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
29b0: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
29c0: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
29d0: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
29e0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
29f0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
2a00: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2a10: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2a20: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
2a30: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2a40: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2a50: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2a60: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2a70: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2a80: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2a90: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2aa0: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45  ;.# ifdef SQLITE
2ab0: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20  _UINT64_TYPE.   
2ac0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2ad0: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  UINT64_TYPE sqli
2ae0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73  te_uint64;.# els
2af0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20  e  .    typedef 
2b00: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2b20: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69  e_uint64;.# endi
2b30: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  f.#elif defined(
2b40: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2b50: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2b60: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2b70: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2b80: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2b90: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2ba0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2bb0: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2bc0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2bd0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2be0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2bf0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2c00: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2c10: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2c30: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2c40: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2c50: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2c60: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2c70: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2c80: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2c90: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2ca0: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2cb0: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2cc0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2cd0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2ce0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2cf0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2d00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2d10: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2d20: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2d30: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2d40: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2d50: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2d60: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2d70: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2d80: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2d90: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2da0: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2db0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2dc0: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2dd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2de0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2df0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2e00: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2e10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2e20: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2e30: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2e40: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2e50: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2e60: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2e80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e90: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2ea0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2eb0: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2ec0: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ed0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2ee0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2ef0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2f00: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2f10: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2f20: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2f30: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2f40: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2f50: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2f60: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2f70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2f80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2f90: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2fa0: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2fb0: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2fc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fd0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2fe0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2ff0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
3000: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
3010: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
3020: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
3030: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
3040: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
3050: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
3060: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
3070: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
3080: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
3090: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
30a0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
30b0: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
30c0: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
30d0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
30e0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
30f0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
3100: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
3110: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
3120: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
3130: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3140: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3150: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
3160: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3170: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3180: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3190: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
31a0: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
31b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
31c0: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
31d0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
31e0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31f0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
3200: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
3210: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
3220: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
3230: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3240: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3250: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3260: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3270: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3280: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3290: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
32a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32b0: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
32c0: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
32d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
32e0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
32f0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
3300: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
3310: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3320: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3330: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3340: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3350: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3360: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3370: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3380: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3390: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
33a0: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
33b0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
33c0: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
33d0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
33e0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
33f0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3400: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3410: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3420: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3440: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3450: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3460: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3470: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3480: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3490: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
34a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
34b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
34c0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
34d0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
34e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
34f0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3500: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3510: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3520: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3530: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3540: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3550: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3560: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3570: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3580: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3590: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35a0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
35b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
35c0: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
35d0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
35e0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
35f0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
3600: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
3610: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
3620: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3630: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3640: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3650: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3660: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3670: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3680: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3690: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
36a0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
36b0: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
36c0: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
36d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
36e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
36f0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
3700: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
3710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
3720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
3730: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3740: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3750: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
3760: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
3770: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
3780: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
3790: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
37a0: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
37b0: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
37c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
37e0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
37f0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
3800: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
3810: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
3820: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
3830: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
3840: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
3850: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
3860: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3870: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
3880: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
3890: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
38a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
38b0: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
38c0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
38d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
38e0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
38f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
3900: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
3910: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
3920: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
3930: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3940: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3950: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3960: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
3970: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3980: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
3990: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
39a0: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
39b0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
39c0: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
39d0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
39e0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
39f0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
3a00: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
3a10: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
3a20: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
3a30: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3a40: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
3a50: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
3a60: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3a70: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3a80: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
3a90: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3aa0: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3ab0: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3ac0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3ad0: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
3ae0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3af0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3b00: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
3b10: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
3b20: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
3b30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3b40: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
3b50: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3b60: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
3b70: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
3b90: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3ba0: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3bb0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3bc0: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3bd0: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3be0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3bf0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3c00: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3c10: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3c20: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3c30: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3c40: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3c50: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3c60: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3c70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3c90: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3ca0: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3cb0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3cc0: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3cd0: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3ce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3cf0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3d00: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3d10: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3d20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3d30: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3d40: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3d50: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3d60: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3d70: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3d80: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3d90: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3da0: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3db0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3dc0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3dd0: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3de0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3df0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3e00: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3e10: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3e20: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3e30: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3e40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3e60: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3e70: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e80: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3e90: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3ea0: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3eb0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3ec0: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3ed0: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ee0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3ef0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3f00: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3f10: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3f20: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3f30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3f40: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3f50: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3f60: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3f70: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3f80: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3f90: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3fa0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3fb0: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3fc0: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3fd0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3fe0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3ff0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
4000: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
4010: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
4020: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
4030: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
4040: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
4050: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
4060: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
4070: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
4080: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
4090: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
40a0: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
40b0: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
40c0: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
40d0: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
40e0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
40f0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
4100: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
4110: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
4120: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
4130: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
4140: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4150: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
4160: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
4170: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
4180: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
4190: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
41a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
41b0: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
41c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
41d0: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
41e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
41f0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
4200: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
4210: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4220: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
4230: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4240: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4250: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4260: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4270: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
4280: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
4290: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
42a0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
42b0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
42c0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
42d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
42e0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
42f0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
4300: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4310: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4330: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4340: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4350: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4370: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4380: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4390: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
43a0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
43b0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
43c0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
43d0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
43e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4400: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4410: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4420: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4430: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4450: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4460: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4470: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4480: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4490: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
44a0: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
44b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
44c0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
44d0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
44e0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
44f0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
4500: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4510: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4520: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4530: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4540: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4550: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4560: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4570: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4580: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4590: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
45a0: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
45b0: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
45c0: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
45d0: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
45e0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
45f0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4610: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
4620: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72  /* Generic error
4630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4640: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4650: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4660: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4670: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4680: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4690: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
46a0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
46b0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
46c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
46d0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
46e0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
46f0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
4700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4710: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
4720: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4730: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4760: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4770: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4780: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4790: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
47a0: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
47b0: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
47c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
47d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
47e0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
47f0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
4800: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
4810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4820: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4830: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4840: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4850: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4870: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4880: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4890: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
48a0: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
48b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
48c0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
48d0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
48e0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
48f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4900: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
4910: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
4920: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4930: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4940: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4950: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4960: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4970: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4980: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4990: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
49a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
49b0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
49c0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
49d0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
49e0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
49f0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
4a00: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
4a10: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
4a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4a30: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4a40: 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20 6f  * Internal use o
4a50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
4a60: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4a70: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4a80: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4a90: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4aa0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4ab0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4ac0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
4ad0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
4ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4af0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4b00: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4b10: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4b20: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4b30: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4b40: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4b50: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4b60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b70: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4b80: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4b90: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bb0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4bc0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4bd0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4be0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4c00: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4c10: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4c20: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4c30: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4c40: 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 20      24   /* Not 
4c50: 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
4c60: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4c70: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4c80: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4c90: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4ca0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4cb0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4cc0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4cd0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
4ce0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
4cf0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
4d10: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4d20: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4d30: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4d50: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4d60: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4d70: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4d90: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4da0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4db0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4dc0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4dd0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4de0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4df0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4e00: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4e10: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4e20: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4e30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4e40: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4e50: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4e60: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4e70: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4e80: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4e90: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4ea0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4eb0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ec0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4ed0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4ee0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4ef0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4f00: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4f10: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4f20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f30: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4f40: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4f50: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4f60: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4f70: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4f80: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4f90: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4fa0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4fb0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4fc0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4fd0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4fe0: 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33  .3.8 [dateof:3.3
4ff0: 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72  .8].** and later
5000: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
5010: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
5020: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
5030: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
5040: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
5050: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
5060: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b   errors. These [
5070: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
5080: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c  codes] are enabl
5090: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
50a0: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
50b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
50c0: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
50d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
50e0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
50f0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68  ()] API.  Or, th
5100: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20  e extended code 
5110: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20  for.** the most 
5120: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e  recent error can
5130: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69   be obtained usi
5140: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
5150: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
5160: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
5170: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53 53  QLITE_ERROR_MISS
5180: 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28 53  ING_COLLSEQ   (S
5190: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 31  QLITE_ERROR | (1
51a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
51b0: 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52 59  LITE_ERROR_RETRY
51c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
51d0: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32 3c  LITE_ERROR | (2<
51e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
51f0: 49 54 45 5f 45 52 52 4f 52 5f 53 4e 41 50 53 48  ITE_ERROR_SNAPSH
5200: 4f 54 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  OT          (SQL
5210: 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 33 3c 3c  ITE_ERROR | (3<<
5220: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5230: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
5240: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38  TE_IOERR | (1<<8
5260: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5270: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
5280: 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  AD        (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
52a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52b0: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
52c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52d0: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29  _IOERR | (3<<8))
52e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52f0: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20  IOERR_FSYNC     
5300: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5310: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
5320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5330: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
5340: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5350: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23  OERR | (5<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5370: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20  ERR_TRUNCATE    
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5390: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
53a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53b0: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
53c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53d0: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  RR | (7<<8)).#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
53f0: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_UNLOCK        
5400: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5410: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _RDLOCK         
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5460: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5470: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
5480: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5490: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
54a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54b0: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20  BLOCKED         
54c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54d0: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (11<<8)).#defi
54e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54f0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20  NOMEM           
5500: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5510: 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (12<<8)).#defi
5520: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5530: 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20  ACCESS          
5540: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5550: 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (13<<8)).#defi
5560: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5570: 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43  CHECKRESERVEDLOC
5580: 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  K (SQLITE_IOERR 
5590: 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (14<<8)).#defi
55a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
55b0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
55c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55d0: 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (15<<8)).#defi
55e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
55f0: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20  CLOSE           
5600: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5610: 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (16<<8)).#defi
5620: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5630: 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  DIR_CLOSE       
5640: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5650: 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (17<<8)).#defi
5660: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5670: 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20  SHMOPEN         
5680: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5690: 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (18<<8)).#defi
56a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
56b0: 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20  SHMSIZE         
56c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
56d0: 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (19<<8)).#defi
56e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
56f0: 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  SHMLOCK         
5700: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5710: 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (20<<8)).#defi
5720: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5730: 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  SHMMAP          
5740: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5750: 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (21<<8)).#defi
5760: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5770: 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20  SEEK            
5780: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5790: 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (22<<8)).#defi
57a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
57b0: 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20  DELETE_NOENT    
57c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
57d0: 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (23<<8)).#defi
57e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
57f0: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
5800: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5810: 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (24<<8)).#defi
5820: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5830: 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20  GETTEMPPATH     
5840: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5850: 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (25<<8)).#defi
5860: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5870: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20  CONVPATH        
5880: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5890: 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (26<<8)).#defi
58a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
58b0: 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20 20  VNODE           
58c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
58d0: 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (27<<8)).#defi
58e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
58f0: 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20 20  AUTH            
5900: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5910: 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (28<<8)).#defi
5920: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5930: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20 20  BEGIN_ATOMIC    
5940: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5950: 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (29<<8)).#defi
5960: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5970: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20 20  COMMIT_ATOMIC   
5980: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5990: 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (30<<8)).#defi
59a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
59b0: 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 20  ROLLBACK_ATOMIC 
59c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
59d0: 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (31<<8)).#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
59f0: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5a00: 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44    (SQLITE_LOCKED
5a10: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
5a20: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5a30: 44 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 20  D_VTAB          
5a40: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5a50: 44 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65  D |  (2<<8)).#de
5a60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5a70: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5a80: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5a90: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5aa0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5ab0: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5ac0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5ad0: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5ae0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5af0: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5b00: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5b10: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b30: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5b40: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5b50: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5b60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5b70: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5b80: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5b90: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5ba0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5bb0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5bc0: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5bd0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5be0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5bf0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 44  QLITE_CANTOPEN_D
5c00: 49 52 54 59 57 41 4c 20 20 20 20 20 20 20 28 53  IRTYWAL       (S
5c10: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5c20: 20 28 35 3c 3c 38 29 29 20 2f 2a 20 4e 6f 74 20   (5<<8)) /* Not 
5c30: 55 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Used */.#define 
5c40: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56  SQLITE_CORRUPT_V
5c50: 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28  TAB            (
5c60: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c  SQLITE_CORRUPT |
5c70: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5c80: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5c90: 53 45 51 55 45 4e 43 45 20 20 20 20 20 20 20 20  SEQUENCE        
5ca0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5cb0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5cc0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5cd0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5ce0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5cf0: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<8)).#def
5d00: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5d10: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
5d20: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5d30: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  NLY | (2<<8)).#d
5d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5d50: 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20  DONLY_ROLLBACK  
5d60: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5d70: 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a  DONLY | (3<<8)).
5d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5d90: 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20  EADONLY_DBMOVED 
5da0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5db0: 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29  EADONLY | (4<<8)
5dc0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5dd0: 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49 4e  _READONLY_CANTIN
5de0: 49 54 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  IT       (SQLITE
5df0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c 3c  _READONLY | (5<<
5e00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5e10: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52 45  TE_READONLY_DIRE
5e20: 43 54 4f 52 59 20 20 20 20 20 20 28 53 51 4c 49  CTORY      (SQLI
5e30: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 36  TE_READONLY | (6
5e40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5e50: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
5e60: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
5e70: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
5e80: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5e90: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5ea0: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  HECK        (SQL
5eb0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5ec0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5ed0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ee0: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20  NT_COMMITHOOK   
5ef0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5f00: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  NT | (2<<8)).#de
5f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5f20: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45  TRAINT_FOREIGNKE
5f30: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5f40: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29  TRAINT | (3<<8))
5f50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f60: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54  CONSTRAINT_FUNCT
5f70: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ION     (SQLITE_
5f80: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c  CONSTRAINT | (4<
5f90: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5fa0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e  ITE_CONSTRAINT_N
5fb0: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c  OTNULL      (SQL
5fc0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5fd0: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5fe0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ff0: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20  NT_PRIMARYKEY   
6000: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6010: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  NT | (6<<8)).#de
6020: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
6030: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20  TRAINT_TRIGGER  
6040: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
6050: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29  TRAINT | (7<<8))
6060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6070: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55  CONSTRAINT_UNIQU
6080: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  E       (SQLITE_
6090: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c  CONSTRAINT | (8<
60a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
60b0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56  ITE_CONSTRAINT_V
60c0: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAB         (SQL
60d0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
60e0: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
60f0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
6100: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20  NT_ROWID        
6110: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6120: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65  NT |(10<<8)).#de
6130: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
6140: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
6150: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
6160: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
6170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
6180: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
6190: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
61a0: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
61b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
61c0: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
61d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
61e0: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ING | (1<<8)).#d
61f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
6200: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20  H_USER          
6210: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54       (SQLITE_AUT
6220: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  H | (1<<8)).#def
6230: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f  ine SQLITE_OK_LO
6240: 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20  AD_PERMANENTLY  
6250: 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20     (SQLITE_OK | 
6260: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
6270: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
6280: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
6290: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
62a0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
62b0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
62c0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
62d0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
62e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
62f0: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
6300: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
6310: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
6320: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
6330: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
6340: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6350: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
6360: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6370: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
6380: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6390: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
63a0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
63b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
63c0: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
63d0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
63e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
63f0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
6400: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6410: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
6420: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6430: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6440: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
6450: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
6460: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
6470: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6480: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
6490: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
64a0: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
64b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
64c0: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
64d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
64e0: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
64f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6500: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
6510: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6520: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
6530: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6550: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
6560: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6570: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
6580: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6590: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
65a0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
65b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
65c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
65d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
65e0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
65f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
6600: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6610: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6620: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
6630: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
6640: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6650: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6660: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
6670: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
6680: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6690: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
66a0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
66b0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
66c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
66d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
66e0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
66f0: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
6700: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6710: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6720: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
6730: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
6740: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6750: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6760: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
6770: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
6780: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6790: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
67a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
67b0: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
67c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
67d0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
67e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
67f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6800: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
6810: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
6820: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6830: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6840: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6850: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
6860: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
6870: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6880: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6890: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
68a0: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
68b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
68c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
68d0: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
68e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
68f0: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
6900: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
6910: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
6920: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
6930: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
6940: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
6950: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
6960: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6970: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
6980: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
6990: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
69a0: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
69b0: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
69c0: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
69d0: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
69e0: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
69f0: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
6a00: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
6a10: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
6a20: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
6a30: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
6a40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6a50: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
6a60: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
6a70: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
6a80: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
6a90: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6aa0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
6ab0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
6ac0: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
6ad0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
6ae0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
6af0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
6b00: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
6b10: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
6b20: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
6b30: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
6b40: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6b50: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
6b60: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
6b70: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
6b80: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
6b90: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
6ba0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
6bb0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
6bc0: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
6bd0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
6be0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
6bf0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
6c00: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6c10: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
6c20: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
6c30: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
6c40: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
6c50: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
6c60: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
6c70: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
6c80: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6c90: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
6ca0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
6cb0: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
6cc0: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
6cd0: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
6ce0: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
6cf0: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
6d00: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
6d10: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
6d20: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
6d30: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
6d40: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
6d50: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
6d60: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
6d70: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
6d80: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
6d90: 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51  changed.  The SQ
6da0: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
6db0: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
6dc0: 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74  .** flag indicat
6dd0: 65 73 20 74 68 61 74 20 61 20 66 69 6c 65 20 63  es that a file c
6de0: 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64  annot be deleted
6df0: 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65   when open.  The
6e00: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  .** SQLITE_IOCAP
6e10: 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20  _IMMUTABLE flag 
6e20: 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
6e30: 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a  he file is on.**
6e40: 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61   read-only media
6e50: 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63   and cannot be c
6e60: 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70  hanged even by p
6e70: 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a  rocesses with.**
6e80: 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c   elevated privil
6e90: 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eges..**.** The 
6ea0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54  SQLITE_IOCAP_BAT
6eb0: 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  CH_ATOMIC proper
6ec0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ty means that th
6ed0: 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20  e underlying.** 
6ee0: 66 69 6c 65 73 79 73 74 65 6d 20 73 75 70 70 6f  filesystem suppo
6ef0: 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69 70  rts doing multip
6f00: 6c 65 20 77 72 69 74 65 20 6f 70 65 72 61 74 69  le write operati
6f10: 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20 77  ons atomically w
6f20: 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72 69  hen those.** wri
6f30: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  te operations ar
6f40: 65 20 62 72 61 63 6b 65 74 65 64 20 62 79 20 5b  e bracketed by [
6f50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
6f60: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
6f70: 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   and.** [SQLITE_
6f80: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
6f90: 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a 23  MIC_WRITE]..*/.#
6fa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6fb0: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
6fc0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6fd0: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
6fe0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6ff0: 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20  C512            
7000: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
7010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
7020: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
7030: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
7040: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
7050: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
7060: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
7070: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
7080: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
7090: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
70a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
70b0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
70c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20  _IOCAP_ATOMIC8K 
70d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
70e0: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65  00000020.#define
70f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
7100: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20  OMIC16K         
7110: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
7120: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7130: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
7140: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
7150: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
7160: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7170: 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20  IC64K           
7180: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
7190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
71a0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20  AP_SAFE_APPEND  
71b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
71c0: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
71d0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
71e0: 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  TIAL            
71f0: 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66   0x00000400.#def
7200: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
7210: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
7220: 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38  N_OPEN  0x000008
7230: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
7240: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
7250: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30  E_OVERWRITE    0
7260: 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e  x00001000.#defin
7270: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49  e SQLITE_IOCAP_I
7280: 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20 20  MMUTABLE        
7290: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
72a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
72b0: 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d  IOCAP_BATCH_ATOM
72c0: 49 43 20 20 20 20 20 20 20 20 20 20 20 30 78 30  IC           0x0
72d0: 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0004000../*.** C
72e0: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
72f0: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
7300: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
7310: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
7320: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
7330: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
7340: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
7350: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
7360: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
7370: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
7380: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
7390: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
73a0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
73b0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
73c0: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
73d0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
73e0: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
73f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
7400: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
7410: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7420: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
7430: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
7440: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
7450: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
7460: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
7470: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
7480: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
7490: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
74a0: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
74b0: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
74c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
74d0: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
74e0: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
74f0: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
7500: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
7510: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
7520: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
7530: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
7540: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
7550: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
7560: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
7570: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
7580: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
7590: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
75a0: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
75b0: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
75c0: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
75d0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
75e0: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
75f0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
7600: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
7610: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
7620: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
7630: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
7640: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
7650: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
7660: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
7670: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
7680: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
7690: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
76a0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
76b0: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
76c0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
76d0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
76e0: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
76f0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
7700: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
7710: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
7720: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
7730: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
7740: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
7750: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
7760: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
7770: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
7780: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
7790: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
77a0: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
77b0: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
77c0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
77d0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
77e0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
77f0: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
7800: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
7810: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
7820: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
7830: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
7840: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
7850: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
7860: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
7870: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
7880: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
7890: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
78a0: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
78b0: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
78c0: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
78d0: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
78e0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
78f0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
7900: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
7910: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
7920: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
7930: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
7940: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
7950: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
7960: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
7970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7980: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
7990: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
79a0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
79b0: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
79c0: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
79d0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
79e0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
79f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
7a00: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
7a10: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
7a20: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
7a30: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
7a40: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
7a50: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
7a60: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
7a70: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
7a80: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
7a90: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
7aa0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
7ab0: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
7ac0: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
7ad0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
7ae0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
7af0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
7b00: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
7b10: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
7b20: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
7b30: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
7b40: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
7b50: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
7b60: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
7b70: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
7b80: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
7b90: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
7ba0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
7bb0: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
7bc0: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
7bd0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
7be0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
7bf0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
7c00: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
7c10: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
7c20: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
7c30: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7c40: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
7c50: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
7c60: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
7c70: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
7c80: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7c90: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
7ca0: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
7cb0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7cc0: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
7cd0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
7ce0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
7cf0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7d00: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
7d10: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
7d20: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
7d30: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
7d40: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
7d50: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
7d60: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
7d70: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
7d80: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
7d90: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
7da0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
7db0: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
7dc0: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
7dd0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7de0: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
7df0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7e00: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
7e10: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
7e20: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
7e30: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7e40: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
7e50: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
7e60: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
7e70: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7e80: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
7e90: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
7ea0: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
7eb0: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
7ec0: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
7ed0: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
7ee0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
7ef0: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
7f00: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7f10: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
7f20: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7f30: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
7f40: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
7f50: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7f60: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
7f70: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
7f80: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
7f90: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
7fa0: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
7fb0: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
7fc0: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
7fd0: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
7fe0: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
7ff0: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
8000: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
8010: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
8020: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
8030: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
8040: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
8050: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
8060: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
8070: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
8080: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
8090: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
80a0: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
80b0: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
80c0: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
80d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
80e0: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
80f0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
8100: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
8110: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
8120: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
8130: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
8140: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
8150: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
8160: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
8170: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
8180: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
8190: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
81a0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
81b0: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
81c0: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
81d0: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
81e0: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
81f0: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
8200: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
8210: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
8220: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
8230: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
8240: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
8250: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
8260: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
8270: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
8280: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
8290: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
82a0: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
82b0: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
82c0: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
82d0: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
82e0: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
82f0: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
8300: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
8310: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
8320: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
8330: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
8340: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8350: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
8360: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
8370: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
8380: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
8390: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
83a0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
83b0: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
83c0: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
83d0: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
83e0: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
83f0: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
8400: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
8410: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
8420: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
8430: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
8440: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
8450: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
8460: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
8470: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
8480: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
8490: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
84a0: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
84b0: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
84c0: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
84d0: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
84e0: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
84f0: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
8500: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
8510: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
8520: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
8530: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
8540: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
8550: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
8560: 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A [file control 
8570: 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f  opcodes | list o
8580: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
8590: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
85a0: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
85b0: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
85c0: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
85d0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
85e0: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
85f0: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
8600: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
8610: 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20  conflicts.  VFS 
8620: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
8630: 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
8640: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
8650: 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74  D] for file cont
8660: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74  rol opcodes that
8670: 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
8680: 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a  recognize..**.**
8690: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
86a0: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
86b0: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
86c0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
86d0: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
86e0: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
86f0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
8700: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
8710: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
8720: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
8730: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
8740: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
8750: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
8760: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
8770: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
8780: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
8790: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
87a0: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
87b0: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
87c0: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
87d0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
87e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
87f0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8800: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
8810: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
8820: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
8830: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8840: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
8850: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8860: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
8870: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8880: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
8890: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
88a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
88b0: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
88c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
88d0: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
88e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
88f0: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
8900: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8910: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
8920: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
8930: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c  EQUENTIAL].** <l
8940: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8950: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
8960: 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20  N_OPEN].** <li> 
8970: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f  [SQLITE_IOCAP_PO
8980: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
8990: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
89a0: 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
89b0: 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  LE].** <li> [SQL
89c0: 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f  ITE_IOCAP_BATCH_
89d0: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ATOMIC].** </ul>
89e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
89f0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
8a00: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
8a10: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
8a20: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
8a30: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8a40: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8a50: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
8a60: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
8a70: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
8a80: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
8a90: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
8aa0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
8ab0: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
8ac0: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
8ad0: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
8ae0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8af0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
8b00: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
8b10: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
8b20: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
8b30: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
8b40: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
8b50: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
8b60: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
8b70: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
8b80: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
8b90: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
8ba0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8bb0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
8bc0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8bd0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
8be0: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
8bf0: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
8c00: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
8c10: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
8c20: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
8c30: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
8c40: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
8c50: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
8c60: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
8c70: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
8c80: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
8c90: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
8ca0: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
8cb0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
8cc0: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
8cd0: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
8ce0: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
8cf0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
8d00: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
8d10: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
8d20: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
8d30: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
8d40: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
8d50: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
8d60: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
8d70: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
8d80: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
8d90: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
8da0: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
8db0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8dc0: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
8dd0: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
8de0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
8df0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8e00: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
8e10: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
8e20: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
8e30: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
8e40: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
8e50: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
8e60: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
8e70: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
8e80: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
8e90: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8ea0: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
8eb0: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
8ec0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8ed0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
8ee0: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
8ef0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8f00: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
8f10: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
8f20: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
8f30: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
8f40: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
8f50: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
8f60: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
8f70: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
8f80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8f90: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
8fa0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
8fb0: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
8fc0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8fd0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
8fe0: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
8ff0: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74  file*);.  /* Met
9000: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
9010: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
9020: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53   1 */.  int (*xS
9030: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  hmMap)(sqlite3_f
9040: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69  ile*, int iPg, i
9050: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f  nt pgsz, int, vo
9060: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a  id volatile**);.
9070: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b    int (*xShmLock
9080: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
9090: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74   int offset, int
90a0: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a   n, int flags);.
90b0: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72    void (*xShmBar
90c0: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69  rier)(sqlite3_fi
90d0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  le*);.  int (*xS
90e0: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33  hmUnmap)(sqlite3
90f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65  _file*, int dele
9100: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65  teFlag);.  /* Me
9110: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
9120: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
9130: 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 2 */.  int (*x
9140: 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66  Fetch)(sqlite3_f
9150: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
9160: 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69  t64 iOfst, int i
9170: 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b  Amt, void **pp);
9180: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63  .  int (*xUnfetc
9190: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
91a0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
91b0: 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b  iOfst, void *p);
91c0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
91d0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
91e0: 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20  r version 3 */. 
91f0: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d   /* Additional m
9200: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64  ethods may be ad
9210: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
9220: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  leases */.};../*
9230: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
9240: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74  andard File Cont
9250: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b  rol Opcodes.** K
9260: 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63  EYWORDS: {file c
9270: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20  ontrol opcodes} 
9280: 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  {file control op
9290: 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  code}.**.** Thes
92a0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
92b0: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
92c0: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
92d0: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
92e0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
92f0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
9300: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
9310: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9320: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
9330: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ace..**.** <ul>.
9340: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9350: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
9360: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9370: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
9380: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9390: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
93a0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
93b0: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
93c0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
93d0: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
93e0: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
93f0: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
9400: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
9410: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
9420: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
9430: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
9440: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
9450: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
9460: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
9470: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
9480: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
9490: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
94a0: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
94b0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
94c0: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
94d0: 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f  testing and is o
94e0: 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68  nly available wh
94f0: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  en the SQLITE_TE
9500: 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  ST.** compile-ti
9510: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  me option is use
9520: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
9530: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
9540: 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _HINT]].** The [
9550: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
9560: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
9570: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
9580: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
9590: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
95a0: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
95b0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
95c0: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
95d0: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
95e0: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
95f0: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
9600: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
9610: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
9620: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
9630: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
9640: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
9650: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
9660: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
9670: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
9680: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
9690: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
96a0: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
96b0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
96c0: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
96d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
96e0: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
96f0: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
9700: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
9710: 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  SIZE] opcode is 
9720: 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20  used to request 
9730: 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20  that the VFS.** 
9740: 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e  extends and trun
9750: 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61  cates the databa
9760: 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b  se file in chunk
9770: 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63  s of a size spec
9780: 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
9790: 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68  user. The fourth
97a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
97b0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
97c0: 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a  ol()] should .**
97d0: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74   point to an int
97e0: 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20  eger (type int) 
97f0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
9800: 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f  ew chunk-size to
9810: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20   use.** for the 
9820: 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61  nominated databa
9830: 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64  se. Allocating d
9840: 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61  atabase file spa
9850: 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63  ce in large.** c
9860: 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61  hunks (say 1MB a
9870: 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72  t a time), may r
9880: 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65  educe file-syste
9890: 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20  m fragmentation 
98a0: 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70  and.** improve p
98b0: 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f  erformance on so
98c0: 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a  me systems..**.*
98d0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
98e0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
98f0: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  R]].** The [SQLI
9900: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
9910: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73  INTER] opcode is
9920: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
9930: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
9940: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
9950: 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69  e] object associ
9960: 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74  ated with a part
9970: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
9980: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
9990: 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45  See also [SQLITE
99a0: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
99b0: 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  OINTER]..**.** <
99c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
99d0: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45  L_JOURNAL_POINTE
99e0: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  R]].** The [SQLI
99f0: 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c  TE_FCNTL_JOURNAL
9a00: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
9a10: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
9a20: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
9a30: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
9a40: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
9a50: 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
9a60: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65   journal file (e
9a70: 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f  ither.** the [ro
9a80: 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20  llback journal] 
9a90: 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68  or the [write-ah
9aa0: 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20  ead log]) for a 
9ab0: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
9ac0: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
9ad0: 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51  n.  See also [SQ
9ae0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
9af0: 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20  POINTER]..**.** 
9b00: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9b10: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d  TL_SYNC_OMITTED]
9b20: 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69  ].** No longer i
9b30: 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  n use..**.** <li
9b40: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9b50: 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SYNC]].** The [S
9b60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
9b70: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65  ] opcode is gene
9b80: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  rated internally
9b90: 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a   by SQLite and.*
9ba0: 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46  * sent to the VF
9bb0: 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65  S immediately be
9bc0: 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d  fore the xSync m
9bd0: 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
9be0: 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73   on a.** databas
9bf0: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  e file descripto
9c00: 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53  r. Or, if the xS
9c10: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f  ync method is no
9c20: 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65  t invoked .** be
9c30: 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68  cause the user h
9c40: 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51  as configured SQ
9c50: 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50  Lite with .** [P
9c60: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
9c70: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
9c80: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69  ronous=OFF] it i
9c90: 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61  s invoked in pla
9ca0: 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53  ce .** of the xS
9cb0: 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d  ync method. In m
9cc0: 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70  ost cases, the p
9cd0: 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20  ointer argument 
9ce0: 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74  passed with.** t
9cf0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
9d00: 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65   is NULL. Howeve
9d10: 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61  r, if the databa
9d20: 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67  se file is being
9d30: 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61   synced.** as pa
9d40: 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61  rt of a multi-da
9d50: 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74  tabase commit, t
9d60: 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  he argument poin
9d70: 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d  ts to a nul-term
9d80: 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
9d90: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
9da0: 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73  transactions mas
9db0: 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  ter-journal file
9dc0: 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61   name. VFSes tha
9dd0: 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65  t .** do not nee
9de0: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68  d this signal sh
9df0: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
9e00: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
9e10: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a  . Applications .
9e20: 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ** should not ca
9e30: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ll [sqlite3_file
9e40: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
9e50: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20   this opcode as 
9e60: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a  doing so may .**
9e70: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
9e80: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
9e90: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
9ea0: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
9eb0: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  it.  .**.** <li>
9ec0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  [[SQLITE_FCNTL_C
9ed0: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d  OMMIT_PHASETWO]]
9ee0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9ef0: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
9f00: 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73  SETWO] opcode is
9f10: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
9f20: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a  nally by SQLite.
9f30: 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74  ** and sent to t
9f40: 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74  he VFS after a t
9f50: 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62  ransaction has b
9f60: 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d  een committed im
9f70: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74  mediately.** but
9f80: 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61   before the data
9f90: 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64  base is unlocked
9fa0: 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  . VFSes that do 
9fb0: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69  not need this si
9fc0: 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73  gnal.** should s
9fd0: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74  ilently ignore t
9fe0: 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c  his opcode. Appl
9ff0: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
a000: 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  not call.** [sql
a010: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
a020: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
a030: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
a040: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68  o may disrupt th
a050: 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  e .** operation 
a060: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
a070: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
a080: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
a090: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a0a0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
a0b0: 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65  _RETRY]].** ^The
a0c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
a0d0: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f  IN32_AV_RETRY] o
a0e0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
a0f0: 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d   configure autom
a100: 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f  atic.** retry co
a110: 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61  unts and interva
a120: 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64  ls for certain d
a130: 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  isk I/O operatio
a140: 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69  ns for the.** wi
a150: 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f  ndows [VFS] in o
a160: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
a170: 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68  robustness in th
a180: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a  e presence of.**
a190: 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67   anti-virus prog
a1a0: 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c  rams.  By defaul
a1b0: 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56  t, the windows V
a1c0: 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69  FS will retry fi
a1d0: 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65  le read,.** file
a1e0: 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65   write, and file
a1f0: 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f   delete operatio
a200: 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65  ns up to 10 time
a210: 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a  s, with a delay.
a220: 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65  ** of 25 millise
a230: 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65  conds before the
a240: 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64   first retry and
a250: 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20   with the delay 
a260: 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79  increasing.** by
a270: 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32   an additional 2
a280: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77  5 milliseconds w
a290: 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75  ith each subsequ
a2a0: 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73  ent retry.  This
a2b0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77  .** opcode allow
a2c0: 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75  s these two valu
a2d0: 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61  es (10 retries a
a2e0: 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  nd 25 millisecon
a2f0: 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20  ds of delay).** 
a300: 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20  to be adjusted. 
a310: 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20   The values are 
a320: 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20  changed for all 
a330: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
a340: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74  ions.** within t
a350: 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e  he same process.
a360: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69    The argument i
a370: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
a380: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a  n array of two.*
a390: 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65  * integers where
a3a0: 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67   the first integ
a3b0: 65 72 20 69 73 20 74 68 65 20 6e 65 77 20 72 65  er is the new re
a3c0: 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68  try count and th
a3d0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65  e second.** inte
a3e0: 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79  ger is the delay
a3f0: 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74  .  If either int
a400: 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eger is negative
a410: 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69  , then the setti
a420: 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  ng.** is not cha
a430: 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64  nged but instead
a440: 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
a450: 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67   of that setting
a460: 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69   is written.** i
a470: 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e  nto the array en
a480: 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68  try, allowing th
a490: 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20  e current retry 
a4a0: 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a  settings to be.*
a4b0: 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20  * interrogated. 
a4c0: 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72   The zDbName par
a4d0: 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65  ameter is ignore
a4e0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
a4f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
a500: 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68  IST_WAL]].** ^Th
a510: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a520: 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63  PERSIST_WAL] opc
a530: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
a540: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
a550: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57  ** persistent [W
a560: 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64  AL | Write Ahead
a570: 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20   Log] setting.  
a580: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
a590: 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69  auxiliary.** wri
a5a0: 74 65 20 61 68 65 61 64 20 6c 6f 67 20 28 5b 57  te ahead log ([W
a5b0: 41 4c 20 66 69 6c 65 5d 29 20 61 6e 64 20 73 68  AL file]) and sh
a5c0: 61 72 65 64 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66  ared memory.** f
a5d0: 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72  iles used for tr
a5e0: 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
a5f0: 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74  l.** are automat
a600: 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77  ically deleted w
a610: 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63  hen the latest c
a620: 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65  onnection to the
a630: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f   database.** clo
a640: 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65  ses.  Setting pe
a650: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
a660: 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66  e causes those f
a670: 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20  iles to persist 
a680: 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20  after.** close. 
a690: 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20   Persisting the 
a6a0: 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20  files is useful 
a6b0: 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65  when other proce
a6c0: 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  sses that do not
a6d0: 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70  .** have write p
a6e0: 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65  ermission on the
a6f0: 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61   directory conta
a700: 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  ining the databa
a710: 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20  se file want.** 
a720: 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61  to read the data
a730: 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68  base file, as th
a740: 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64  e WAL and shared
a750: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75   memory files mu
a760: 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f  st exist.** in o
a770: 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74  rder for the dat
a780: 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64  abase to be read
a790: 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74  able.  The fourt
a7a0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
a7b0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
a7c0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74  control()] for t
a7d0: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c  his opcode shoul
a7e0: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  d be a pointer t
a7f0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  o an integer..**
a800: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73   That integer is
a810: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65   0 to disable pe
a820: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
a830: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
a840: 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57   persistent.** W
a850: 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  AL mode.  If the
a860: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
a870: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
a880: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
a890: 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70  current.** WAL p
a8a0: 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69  ersistence setti
a8b0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
a8c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
a8d0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
a8e0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a8f0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a900: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70  FE_OVERWRITE] op
a910: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
a920: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
a930: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22  .** persistent "
a940: 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72  powersafe-overwr
a950: 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73  ite" or "PSOW" s
a960: 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f  etting.  The PSO
a970: 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74  W setting.** det
a980: 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c  ermines the [SQL
a990: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
a9a0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62  AFE_OVERWRITE] b
a9b0: 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65  it of the.** xDe
a9c0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
a9d0: 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65  ics methods. The
a9e0: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
a9f0: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
aa00: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
aa10: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
aa20: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
aa30: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
aa40: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
aa50: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
aa60: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  ble zero-damage 
aa70: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
aa80: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a  ble zero-damage.
aa90: 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ** mode.  If the
aaa0: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
aab0: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
aac0: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
aad0: 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d  current.** zero-
aae0: 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74  damage mode sett
aaf0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
ab00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
ab10: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
ab20: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
ab30: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
ab40: 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  e is invoked by 
ab50: 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65  SQLite after ope
ab60: 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20  ning.** a write 
ab70: 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69  transaction to i
ab80: 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e  ndicate that, un
ab90: 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65  less it is rolle
aba0: 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a  d back for some.
abb0: 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65  ** reason, the e
abc0: 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66  ntire database f
abd0: 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72  ile will be over
abe0: 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63  written by the c
abf0: 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73  urrent .** trans
ac00: 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20  action. This is 
ac10: 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f  used by VACUUM o
ac20: 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
ac30: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
ac40: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a  NTL_VFSNAME]].**
ac50: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
ac60: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63  NTL_VFSNAME] opc
ac70: 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ode can be used 
ac80: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61  to obtain the na
ac90: 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56  mes of.** all [V
aca0: 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53  FSes] in the VFS
acb0: 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d   stack.  The nam
acc0: 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46  es are of all VF
acd0: 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a  S shims and the.
ace0: 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d  ** final bottom-
acf0: 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72  level VFS are wr
ad00: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
ad10: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
ad20: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
ad30: 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72  loc()] and the r
ad40: 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20  esult is stored 
ad50: 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  in the char* var
ad60: 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68  iable.** that th
ad70: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
ad80: 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66  er of [sqlite3_f
ad90: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70  ile_control()] p
ada0: 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65  oints to..** The
adb0: 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f   caller is respo
adc0: 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69  nsible for freei
add0: 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68  ng the memory wh
ade0: 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74  en done.  As wit
adf0: 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f  h.** all file-co
ae00: 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74  ntrol actions, t
ae10: 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61  here is no guara
ae20: 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77  ntee that this w
ae30: 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  ill actually.** 
ae40: 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61  do anything.  Ca
ae50: 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69  llers should ini
ae60: 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72  tialize the char
ae70: 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20  * variable to a 
ae80: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
ae90: 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c  in case this fil
aea0: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74  e-control is not
aeb0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54   implemented.  T
aec0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
aed0: 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20  .** is intended 
aee0: 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75  for diagnostic u
aef0: 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c  se only..**.** <
af00: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
af10: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a  L_VFS_POINTER]].
af20: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
af30: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
af40: 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20  R] opcode finds 
af50: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
af60: 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56   top-level.** [V
af70: 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20  FSes] currently 
af80: 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61  in use.  ^(The a
af90: 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20  rgument X in.** 
afa0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
afb0: 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46  trol(db,SQLITE_F
afc0: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
afd0: 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f  ,X) must be.** o
afe0: 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33  f type "[sqlite3
aff0: 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73  _vfs] **".  This
b000: 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65   opcodes will se
b010: 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69  t *X.** to a poi
b020: 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d  nter to the top-
b030: 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20  level VFS.)^.** 
b040: 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72 65 20  ^When there are 
b050: 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69  multiple VFS shi
b060: 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c  ms in the stack,
b070: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e   this opcode fin
b080: 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d  ds the.** upper-
b090: 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a  most shim only..
b0a0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b0b0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
b0c0: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61  ].** ^Whenever a
b0d0: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
b0e0: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61  ent is parsed, a
b0f0: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  n [SQLITE_FCNTL_
b100: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65  PRAGMA] .** file
b110: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74   control is sent
b120: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71   to the open [sq
b130: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
b140: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ct corresponding
b150: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62  .** to the datab
b160: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63  ase file to whic
b170: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61  h the pragma sta
b180: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e  tement refers. ^
b190: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  The argument.** 
b1a0: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  to the [SQLITE_F
b1b0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
b1c0: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20  e control is an 
b1d0: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e  array of.** poin
b1e0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
b1f0: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63  (char**) in whic
b200: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65  h the second ele
b210: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61  ment of the arra
b220: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  y.** is the name
b230: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61   of the pragma a
b240: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65  nd the third ele
b250: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75  ment is the argu
b260: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70  ment to the.** p
b270: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66  ragma or NULL if
b280: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20   the pragma has 
b290: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  no argument.  ^T
b2a0: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  he handler for a
b2b0: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  n.** [SQLITE_FCN
b2c0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
b2d0: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69  control can opti
b2e0: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20  onally make the 
b2f0: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a  first element.**
b300: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61   of the char** a
b310: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f  rgument point to
b320: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e   a string obtain
b330: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
b340: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f  _mprintf()].** o
b350: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
b360: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67   and that string
b370: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
b380: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70   result of the p
b390: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20  ragma or.** the 
b3a0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66  error message if
b3b0: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c   the pragma fail
b3c0: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  s. ^If the.** [S
b3d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b3e0: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
b3f0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
b400: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e  _NOTFOUND], then
b410: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41   normal .** [PRA
b420: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20  GMA] processing 
b430: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20  continues.  ^If 
b440: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
b450: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
b460: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
b470: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
b480: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61  hen the parser a
b490: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
b4a0: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c  ** VFS has handl
b4b0: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74  ed the PRAGMA it
b4c0: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72  self and the par
b4d0: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20  ser generates a 
b4e0: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65  no-op.** prepare
b4f0: 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72  d statement if r
b500: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20  esult string is 
b510: 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65  NULL, or that re
b520: 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20  turns a copy.** 
b530: 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 74  of the result st
b540: 72 69 6e 67 20 69 66 20 74 68 65 20 73 74 72 69  ring if the stri
b550: 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a  ng is non-NULL..
b560: 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
b570: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
b580: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
b590: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73  turns.** any res
b5a0: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74  ult code other t
b5b0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  han [SQLITE_OK] 
b5c0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  or [SQLITE_NOTFO
b5d0: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  UND], that means
b5e0: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53  .** that the VFS
b5f0: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20   encountered an 
b600: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64  error while hand
b610: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  ling the [PRAGMA
b620: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  ] and the.** com
b630: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  pilation of the 
b640: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74  PRAGMA fails wit
b650: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68  h an error.  ^Th
b660: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b670: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
b680: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61  control occurs a
b690: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  t the beginning 
b6a0: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  of pragma statem
b6b0: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64  ent analysis and
b6c0: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c   so.** it is abl
b6d0: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75  e to override bu
b6e0: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20  ilt-in [PRAGMA] 
b6f0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
b700: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b710: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
b720: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
b730: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
b740: 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f  DLER].** file-co
b750: 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76  ntrol may be inv
b760: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f  oked by SQLite o
b770: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
b780: 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68  ile handle.** sh
b790: 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69  ortly after it i
b7a0: 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65  s opened in orde
b7b0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63  r to provide a c
b7c0: 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61  ustom VFS with a
b7d0: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20  ccess.** to the 
b7e0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79  connections busy
b7f0: 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
b800: 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  k. The argument 
b810: 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  is of type (void
b820: 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72   **).** - an arr
b830: 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20  ay of two (void 
b840: 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66  *) values. The f
b850: 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63  irst (void *) ac
b860: 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a  tually points.**
b870: 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
b880: 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28  f type (int (*)(
b890: 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64  void *)). In ord
b8a0: 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  er to invoke the
b8b0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
b8c0: 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68  busy-handler, th
b8d0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  is function shou
b8e0: 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ld be invoked wi
b8f0: 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76  th the second (v
b900: 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65  oid *) in.** the
b910: 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e   array as the on
b920: 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20  ly argument. If 
b930: 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  it returns non-z
b940: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70  ero, then the op
b950: 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  eration.** shoul
b960: 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66  d be retried. If
b970: 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f   it returns zero
b980: 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53  , the custom VFS
b990: 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20   should abandon 
b9a0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f  the.** current o
b9b0: 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  peration..**.** 
b9c0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b9d0: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
b9e0: 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f  ].** ^Applicatio
b9f0: 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65  n can invoke the
ba00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
ba10: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c  EMPFILENAME] fil
ba20: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20  e-control.** to 
ba30: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65  have SQLite gene
ba40: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72  rate a.** tempor
ba50: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69  ary filename usi
ba60: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
ba70: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f  rithm that is fo
ba80: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61  llowed to genera
ba90: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
baa0: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45  filenames for TE
bab0: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74  MP tables and ot
bac0: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65  her internal use
bad0: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d  s.  The.** argum
bae0: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ent should be a 
baf0: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c  char** which wil
bb00: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68  l be filled with
bb10: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
bb20: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
bb30: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
bb40: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
bb50: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c  oc()].  The call
bb60: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76  er should.** inv
bb70: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
bb80: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75  e()] on the resu
bb90: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65  lt to avoid a me
bba0: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a  mory leak..**.**
bbb0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
bbc0: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  NTL_MMAP_SIZE]].
bbd0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
bbe0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
bbf0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
bc00: 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72  used to query or
bc10: 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69   set the.** maxi
bc20: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
bc30: 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65  tes that will be
bc40: 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79   used for memory
bc50: 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20  -mapped I/O..** 
bc60: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
bc70: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
bc80: 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c  alue of type sql
bc90: 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a  ite3_int64 that.
bca0: 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72  ** is an advisor
bcb0: 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  y maximum number
bcc0: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
bcd0: 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20   file to memory 
bce0: 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69  map.  The.** poi
bcf0: 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74  nter is overwrit
bd00: 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64  ten with the old
bd10: 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d   value.  The lim
bd20: 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  it is not change
bd30: 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75  d if.** the valu
bd40: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69  e originally poi
bd50: 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74  nted to is negat
bd60: 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ive, and so the 
bd70: 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a  current limit .*
bd80: 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64  * can be queried
bd90: 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61   by passing in a
bda0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
bdb0: 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20  gative number.  
bdc0: 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  This.** file-con
bdd0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74  trol is used int
bde0: 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65  ernally to imple
bdf0: 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61  ment [PRAGMA mma
be00: 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  p_size]..**.** <
be10: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
be20: 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65  L_TRACE]].** The
be30: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
be40: 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  RACE] file contr
be50: 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69  ol provides advi
be60: 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  sory information
be70: 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61  .** to the VFS a
be80: 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69  bout what the hi
be90: 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74  gher layers of t
bea0: 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  he SQLite stack 
beb0: 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68  are doing..** Th
bec0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
bed0: 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20  is used by some 
bee0: 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61  VFS activity tra
bef0: 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a  cing [shims]..**
bf00: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
bf10: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
bf20: 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68  ed string.  High
bf30: 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65  er layers in the
bf40: 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b  .** SQLite stack
bf50: 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e   may generate in
bf60: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20  stances of this 
bf70: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a  file control if.
bf80: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  ** the [SQLITE_U
bf90: 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20  SE_FCNTL_TRACE] 
bfa0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
bfb0: 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
bfc0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
bfd0: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
bfe0: 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ED]].** The [SQL
bff0: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
c000: 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  VED] file contro
c010: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73  l interprets its
c020: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a   argument as a.*
c030: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
c040: 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77  integer and it w
c050: 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20  rites a boolean 
c060: 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
c070: 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f  r depending.** o
c080: 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  n whether or not
c090: 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65   the file has be
c0a0: 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65  en renamed, move
c0b0: 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69  d, or deleted si
c0c0: 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69  nce it.** was fi
c0d0: 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a  rst opened..**.*
c0e0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c0f0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
c100: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  ANDLE]].** The [
c110: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c120: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f  32_GET_HANDLE] o
c130: 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65  pcode can be use
c140: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a  d to obtain the.
c150: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61  ** underlying na
c160: 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65  tive file handle
c170: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
c180: 20 61 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20   a file handle. 
c190: 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f   This file.** co
c1a0: 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73  ntrol interprets
c1b0: 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73   its argument as
c1c0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
c1d0: 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64  native file hand
c1e0: 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73  le and.** writes
c1f0: 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 76   the resulting v
c200: 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a  alue there..**.*
c210: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c220: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
c230: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  ANDLE]].** The [
c240: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c250: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f  32_SET_HANDLE] o
c260: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
c270: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
c280: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
c290: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
c2a0: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73  trol method to s
c2b0: 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e  wap the file han
c2c0: 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65  dle with the one
c2d0: 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
c2e0: 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  y the pArg argum
c2f0: 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62  ent.  This capab
c300: 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75  ility is used du
c310: 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20  ring testing.** 
c320: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
c330: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
c340: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20  hen SQLITE_TEST 
c350: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  is defined..**.*
c360: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c370: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d  CNTL_WAL_BLOCK]]
c380: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
c390: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d  FCNTL_WAL_BLOCK]
c3a0: 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20   is a signal to 
c3b0: 74 68 65 20 56 46 53 20 6c 61 79 65 72 20 74 68  the VFS layer th
c3c0: 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62  at it might.** b
c3d0: 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74  e advantageous t
c3e0: 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e  o block on the n
c3f0: 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20  ext WAL lock if 
c400: 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20  the lock is not 
c410: 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61  immediately.** a
c420: 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57  vailable.  The W
c430: 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73 73  AL subsystem iss
c440: 75 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20  ues this signal 
c450: 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63  during rare.** c
c460: 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20  ircumstances in 
c470: 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61 20 70  order to fix a p
c480: 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f  roblem with prio
c490: 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a  rity inversion..
c4a0: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
c4b0: 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f  should <em>not</
c4c0: 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c  em> use this fil
c4d0: 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a  e-control..**.**
c4e0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c4f0: 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20  NTL_ZIPVFS]].** 
c500: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c510: 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65  L_ZIPVFS] opcode
c520: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
c530: 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20  by zipvfs only. 
c540: 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53  All other.** VFS
c550: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53   should return S
c560: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66  QLITE_NOTFOUND f
c570: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a  or this opcode..
c580: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c590: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a  TE_FCNTL_RBU]].*
c5a0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c5b0: 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20  NTL_RBU] opcode 
c5c0: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  is implemented b
c5d0: 79 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  y the special VF
c5e0: 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65  S used by.** the
c5f0: 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f   RBU extension o
c600: 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  nly.  All other 
c610: 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72  VFS should retur
c620: 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e  n SQLITE_NOTFOUN
c630: 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70  D for.** this op
c640: 63 6f 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  code.  .**.** <l
c650: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c660: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52  _BEGIN_ATOMIC_WR
c670: 49 54 45 5d 5d 0a 2a 2a 20 49 66 20 74 68 65 20  ITE]].** If the 
c680: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
c690: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
c6a0: 5d 20 6f 70 63 6f 64 65 20 72 65 74 75 72 6e 73  ] opcode returns
c6b0: 20 53 51 4c 49 54 45 5f 4f 4b 2c 20 74 68 65 6e   SQLITE_OK, then
c6c0: 0a 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73  .** the file des
c6d0: 63 72 69 70 74 6f 72 20 69 73 20 70 6c 61 63 65  criptor is place
c6e0: 64 20 69 6e 20 22 62 61 74 63 68 20 77 72 69 74  d in "batch writ
c6f0: 65 20 6d 6f 64 65 22 2c 20 77 68 69 63 68 0a 2a  e mode", which.*
c700: 2a 20 6d 65 61 6e 73 20 61 6c 6c 20 73 75 62 73  * means all subs
c710: 65 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65  equent write ope
c720: 72 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 20  rations will be 
c730: 64 65 66 65 72 72 65 64 20 61 6e 64 20 64 6f 6e  deferred and don
c740: 65 0a 2a 2a 20 61 74 6f 6d 69 63 61 6c 6c 79 20  e.** atomically 
c750: 61 74 20 74 68 65 20 6e 65 78 74 20 5b 53 51 4c  at the next [SQL
c760: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
c770: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 20  _ATOMIC_WRITE]. 
c780: 20 53 79 73 74 65 6d 73 0a 2a 2a 20 74 68 61 74   Systems.** that
c790: 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20   do not support 
c7a0: 62 61 74 63 68 20 61 74 6f 6d 69 63 20 77 72 69  batch atomic wri
c7b0: 74 65 73 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  tes will return 
c7c0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 2e  SQLITE_NOTFOUND.
c7d0: 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77 69 6e 67 20 61  .** ^Following a
c7e0: 20 73 75 63 63 65 73 73 66 75 6c 20 53 51 4c 49   successful SQLI
c7f0: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
c800: 54 4f 4d 49 43 5f 57 52 49 54 45 20 61 6e 64 20  TOMIC_WRITE and 
c810: 70 72 69 6f 72 20 74 6f 0a 2a 2a 20 74 68 65 20  prior to.** the 
c820: 63 6c 6f 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f  closing [SQLITE_
c830: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
c840: 4d 49 43 5f 57 52 49 54 45 5d 20 6f 72 0a 2a 2a  MIC_WRITE] or.**
c850: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52   [SQLITE_FCNTL_R
c860: 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57  OLLBACK_ATOMIC_W
c870: 52 49 54 45 5d 2c 20 53 51 4c 69 74 65 20 77 69  RITE], SQLite wi
c880: 6c 6c 20 6d 61 6b 65 0a 2a 2a 20 6e 6f 20 56 46  ll make.** no VF
c890: 53 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c  S interface call
c8a0: 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 73  s on the same [s
c8b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 66 69 6c  qlite3_file] fil
c8c0: 65 20 64 65 73 63 72 69 70 74 6f 72 0a 2a 2a 20  e descriptor.** 
c8d0: 65 78 63 65 70 74 20 66 6f 72 20 63 61 6c 6c 73  except for calls
c8e0: 20 74 6f 20 74 68 65 20 78 57 72 69 74 65 20 6d   to the xWrite m
c8f0: 65 74 68 6f 64 20 61 6e 64 20 74 68 65 20 78 46  ethod and the xF
c900: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
c910: 64 0a 2a 2a 20 77 69 74 68 20 5b 53 51 4c 49 54  d.** with [SQLIT
c920: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
c930: 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  T]..**.** <li>[[
c940: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
c950: 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  MIT_ATOMIC_WRITE
c960: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
c970: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41  E_FCNTL_COMMIT_A
c980: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63  TOMIC_WRITE] opc
c990: 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77  ode causes all w
c9a0: 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  rite.** operatio
c9b0: 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70 72 65  ns since the pre
c9c0: 76 69 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c  vious successful
c9d0: 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51   call to .** [SQ
c9e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e  LITE_FCNTL_BEGIN
c9f0: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74  _ATOMIC_WRITE] t
ca00: 6f 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 61  o be performed a
ca10: 74 6f 6d 69 63 61 6c 6c 79 2e 0a 2a 2a 20 54 68  tomically..** Th
ca20: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
ca30: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
ca40: 4f 4b 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  OK] if and only 
ca50: 69 66 20 74 68 65 20 77 72 69 74 65 73 20 77 65  if the writes we
ca60: 72 65 0a 2a 2a 20 61 6c 6c 20 70 65 72 66 6f 72  re.** all perfor
ca70: 6d 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79  med successfully
ca80: 20 61 6e 64 20 68 61 76 65 20 62 65 65 6e 20 63   and have been c
ca90: 6f 6d 6d 69 74 74 65 64 20 74 6f 20 70 65 72 73  ommitted to pers
caa0: 69 73 74 65 6e 74 20 73 74 6f 72 61 67 65 2e 0a  istent storage..
cab0: 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
cac0: 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
cad0: 20 69 74 20 69 73 20 73 75 63 63 65 73 73 66 75   it is successfu
cae0: 6c 2c 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  l, this file con
caf0: 74 72 6f 6c 20 74 61 6b 65 73 0a 2a 2a 20 74 68  trol takes.** th
cb00: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  e file descripto
cb10: 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77  r out of batch w
cb20: 72 69 74 65 20 6d 6f 64 65 20 73 6f 20 74 68 61  rite mode so tha
cb30: 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  t all subsequent
cb40: 0a 2a 2a 20 77 72 69 74 65 20 6f 70 65 72 61 74  .** write operat
cb50: 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e  ions are indepen
cb60: 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  dent..** ^SQLite
cb70: 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
cb80: 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ke SQLITE_FCNTL_
cb90: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52  COMMIT_ATOMIC_WR
cba0: 49 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61  ITE without.** a
cbb0: 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
cbc0: 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54  l call to [SQLIT
cbd0: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54  E_FCNTL_BEGIN_AT
cbe0: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a  OMIC_WRITE]..**.
cbf0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
cc00: 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41  FCNTL_ROLLBACK_A
cc10: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a  TOMIC_WRITE]].**
cc20: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
cc30: 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  TL_ROLLBACK_ATOM
cc40: 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  IC_WRITE] opcode
cc50: 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74   causes all writ
cc60: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20  e.** operations 
cc70: 73 69 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f  since the previo
cc80: 75 73 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  us successful ca
cc90: 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54  ll to .** [SQLIT
cca0: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54  E_FCNTL_BEGIN_AT
ccb0: 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62  OMIC_WRITE] to b
ccc0: 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  e rolled back..*
ccd0: 2a 20 5e 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  * ^This file con
cce0: 74 72 6f 6c 20 74 61 6b 65 73 20 74 68 65 20 66  trol takes the f
ccf0: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20 6f  ile descriptor o
cd00: 75 74 20 6f 66 20 62 61 74 63 68 20 77 72 69 74  ut of batch writ
cd10: 65 20 6d 6f 64 65 0a 2a 2a 20 73 6f 20 74 68 61  e mode.** so tha
cd20: 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  t all subsequent
cd30: 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e   write operation
cd40: 73 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65 6e  s are independen
cd50: 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  t..** ^SQLite wi
cd60: 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
cd70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c  SQLITE_FCNTL_ROL
cd80: 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49  LBACK_ATOMIC_WRI
cd90: 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20  TE without.** a 
cda0: 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
cdb0: 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45   call to [SQLITE
cdc0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
cdd0: 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a  MIC_WRITE]..**.*
cde0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
cdf0: 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55  CNTL_LOCK_TIMEOU
ce00: 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  T]].** The [SQLI
ce10: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49  TE_FCNTL_LOCK_TI
ce20: 4d 45 4f 55 54 5d 20 6f 70 63 6f 64 65 20 63 61  MEOUT] opcode ca
ce30: 75 73 65 73 20 61 74 74 65 6d 70 74 73 20 74 6f  uses attempts to
ce40: 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 20 66 69 6c   obtain.** a fil
ce50: 65 20 6c 6f 63 6b 20 75 73 69 6e 67 20 74 68 65  e lock using the
ce60: 20 78 4c 6f 63 6b 20 6f 72 20 78 53 68 6d 4c 6f   xLock or xShmLo
ce70: 63 6b 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68  ck methods of th
ce80: 65 20 56 46 53 20 74 6f 20 77 61 69 74 0a 2a 2a  e VFS to wait.**
ce90: 20 66 6f 72 20 75 70 20 74 6f 20 4d 20 6d 69 6c   for up to M mil
cea0: 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65  liseconds before
ceb0: 20 66 61 69 6c 69 6e 67 2c 20 77 68 65 72 65 20   failing, where 
cec0: 4d 20 69 73 20 74 68 65 20 73 69 6e 67 6c 65 20  M is the single 
ced0: 0a 2a 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  .** unsigned int
cee0: 65 67 65 72 20 70 61 72 61 6d 65 74 65 72 2e 0a  eger parameter..
cef0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
cf00: 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45  TE_FCNTL_DATA_VE
cf10: 52 53 49 4f 4e 5d 5d 0a 2a 2a 20 54 68 65 20 5b  RSION]].** The [
cf20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41 54  SQLITE_FCNTL_DAT
cf30: 41 5f 56 45 52 53 49 4f 4e 5d 20 6f 70 63 6f 64  A_VERSION] opcod
cf40: 65 20 69 73 20 75 73 65 64 20 74 6f 20 64 65 74  e is used to det
cf50: 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
cf60: 2a 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  * a database fil
cf70: 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
cf80: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
cf90: 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e   a 32-bit unsign
cfa0: 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  ed integer..** T
cfb0: 68 65 20 22 64 61 74 61 20 76 65 72 73 69 6f 6e  he "data version
cfc0: 22 20 66 6f 72 20 74 68 65 20 70 61 67 65 72 20  " for the pager 
cfd0: 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
cfe0: 74 68 65 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  the pointer.  Th
cff0: 65 0a 2a 2a 20 22 64 61 74 61 20 76 65 72 73 69  e.** "data versi
d000: 6f 6e 22 20 63 68 61 6e 67 65 73 20 77 68 65 6e  on" changes when
d010: 65 76 65 72 20 61 6e 79 20 63 68 61 6e 67 65 20  ever any change 
d020: 6f 63 63 75 72 73 20 74 6f 20 74 68 65 20 63 6f  occurs to the co
d030: 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 64  rresponding.** d
d040: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 65 69  atabase file, ei
d050: 74 68 65 72 20 74 68 72 6f 75 67 68 20 53 51 4c  ther through SQL
d060: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 74   statements on t
d070: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
d080: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  .** connection o
d090: 72 20 74 68 72 6f 75 67 68 20 74 72 61 6e 73 61  r through transa
d0a0: 63 74 69 6f 6e 73 20 63 6f 6d 6d 69 74 74 65 64  ctions committed
d0b0: 20 62 79 20 73 65 70 61 72 61 74 65 20 64 61 74   by separate dat
d0c0: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
d0d0: 69 6f 6e 73 20 70 6f 73 73 69 62 6c 79 20 69 6e  ions possibly in
d0e0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
d0f0: 2e 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  . The [sqlite3_t
d100: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a  otal_changes()].
d110: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  ** interface can
d120: 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
d130: 20 69 66 20 61 6e 79 20 64 61 74 61 62 61 73 65   if any database
d140: 20 6f 6e 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   on the connecti
d150: 6f 6e 20 68 61 73 20 63 68 61 6e 67 65 64 2c 0a  on has changed,.
d160: 2a 2a 20 62 75 74 20 74 68 61 74 20 69 6e 74 65  ** but that inte
d170: 72 66 61 63 65 20 72 65 73 70 6f 6e 64 73 20 74  rface responds t
d180: 6f 20 63 68 61 6e 67 65 73 20 6f 6e 20 54 45 4d  o changes on TEM
d190: 50 20 61 73 20 77 65 6c 6c 20 61 73 20 4d 41 49  P as well as MAI
d1a0: 4e 20 61 6e 64 20 64 6f 65 73 0a 2a 2a 20 6e 6f  N and does.** no
d1b0: 74 20 70 72 6f 76 69 64 65 20 61 20 6d 65 63 68  t provide a mech
d1c0: 61 6e 69 73 6d 20 74 6f 20 64 65 74 65 63 74 20  anism to detect 
d1d0: 63 68 61 6e 67 65 73 20 74 6f 20 4d 41 49 4e 20  changes to MAIN 
d1e0: 6f 6e 6c 79 2e 20 20 41 6c 73 6f 2c 20 74 68 65  only.  Also, the
d1f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  .** [sqlite3_tot
d200: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
d210: 74 65 72 66 61 63 65 20 72 65 73 70 6f 6e 64 73  terface responds
d220: 20 74 6f 20 69 6e 74 65 72 6e 61 6c 20 63 68 61   to internal cha
d230: 6e 67 65 73 20 6f 6e 6c 79 20 61 6e 64 0a 2a 2a  nges only and.**
d240: 20 6f 6d 69 74 73 20 63 68 61 6e 67 65 73 20 6d   omits changes m
d250: 61 64 65 20 62 79 20 6f 74 68 65 72 20 64 61 74  ade by other dat
d260: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d270: 73 2e 20 20 54 68 65 0a 2a 2a 20 5b 50 52 41 47  s.  The.** [PRAG
d280: 4d 41 20 64 61 74 61 5f 76 65 72 73 69 6f 6e 5d  MA data_version]
d290: 20 63 6f 6d 6d 61 6e 64 20 70 72 6f 76 69 64 65   command provide
d2a0: 20 61 20 6d 65 63 68 61 6e 69 73 6d 20 74 6f 20   a mechanism to 
d2b0: 64 65 74 65 63 74 20 63 68 61 6e 67 65 73 20 74  detect changes t
d2c0: 6f 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 20 61 74  o.** a single at
d2d0: 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 20  tached database 
d2e0: 74 68 61 74 20 6f 63 63 75 72 20 64 75 65 20 74  that occur due t
d2f0: 6f 20 6f 74 68 65 72 20 64 61 74 61 62 61 73 65  o other database
d300: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2c 0a 2a 2a   connections,.**
d310: 20 62 75 74 20 6f 6d 69 74 73 20 63 68 61 6e 67   but omits chang
d320: 65 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  es implemented b
d330: 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  y the database c
d340: 6f 6e 6e 65 63 74 69 6f 6e 20 6f 6e 20 77 68 69  onnection on whi
d350: 63 68 20 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c  ch it is.** call
d360: 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 20 63  ed.  This file c
d370: 6f 6e 74 72 6f 6c 20 69 73 20 74 68 65 20 6f 6e  ontrol is the on
d380: 6c 79 20 6d 65 63 68 61 6e 69 73 6d 20 74 6f 20  ly mechanism to 
d390: 64 65 74 65 63 74 20 63 68 61 6e 67 65 73 20 74  detect changes t
d3a0: 68 61 74 0a 2a 2a 20 68 61 70 70 65 6e 20 65 69  hat.** happen ei
d3b0: 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ther internally 
d3c0: 6f 72 20 65 78 74 65 72 6e 61 6c 6c 79 20 61 6e  or externally an
d3d0: 64 20 74 68 61 74 20 61 72 65 20 61 73 73 6f 63  d that are assoc
d3e0: 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 61 20  iated with.** a 
d3f0: 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 61 63  particular attac
d400: 68 65 64 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a  hed database..**
d410: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </ul>.*/.#defin
d420: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
d430: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20  OCKSTATE        
d440: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
d450: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45   SQLITE_FCNTL_GE
d460: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
d470: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
d480: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54  SQLITE_FCNTL_SET
d490: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
d4a0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
d4b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54  QLITE_FCNTL_LAST
d4c0: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
d4d0: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
d4e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
d4f0: 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  HINT            
d500: 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
d510: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
d520: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
d530: 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
d540: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
d550: 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20  INTER           
d560: 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
d570: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
d580: 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20  TTED            
d590: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
d5a0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
d5b0: 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39  RETRY          9
d5c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d5d0: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
d5e0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  L            10.
d5f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d600: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20  CNTL_OVERWRITE  
d610: 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23              11.#
d620: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d630: 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20  NTL_VFSNAME     
d640: 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64             12.#d
d650: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d660: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
d670: 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65  RWRITE    13.#de
d680: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d690: 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  L_PRAGMA        
d6a0: 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66           14.#def
d6b0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d6c0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20  _BUSYHANDLER    
d6d0: 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69          15.#defi
d6e0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d6f0: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20  TEMPFILENAME    
d700: 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e         16.#defin
d710: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d  e SQLITE_FCNTL_M
d720: 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20  MAP_SIZE        
d730: 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65        18.#define
d740: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52   SQLITE_FCNTL_TR
d750: 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ACE             
d760: 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20       19.#define 
d770: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53  SQLITE_FCNTL_HAS
d780: 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20  _MOVED          
d790: 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53      20.#define S
d7a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
d7b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d7c0: 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51     21.#define SQ
d7d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
d7e0: 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20  T_PHASETWO      
d7f0: 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    22.#define SQL
d800: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
d810: 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20  SET_HANDLE      
d820: 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   23.#define SQLI
d830: 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f  TE_FCNTL_WAL_BLO
d840: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
d850: 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  24.#define SQLIT
d860: 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20  E_FCNTL_ZIPVFS  
d870: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
d880: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
d890: 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20  _FCNTL_RBU      
d8a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36                26
d8b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d8c0: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
d8d0: 52 20 20 20 20 20 20 20 20 20 20 20 20 32 37 0a  R            27.
d8e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d8f0: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
d900: 4e 54 45 52 20 20 20 20 20 20 20 20 32 38 0a 23  NTER        28.#
d910: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d920: 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41  NTL_WIN32_GET_HA
d930: 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a 23 64  NDLE       29.#d
d940: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d950: 54 4c 5f 50 44 42 20 20 20 20 20 20 20 20 20 20  TL_PDB          
d960: 20 20 20 20 20 20 20 20 20 20 33 30 0a 23 64 65            30.#de
d970: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d980: 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57  L_BEGIN_ATOMIC_W
d990: 52 49 54 45 20 20 20 20 20 33 31 0a 23 64 65 66  RITE     31.#def
d9a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d9b0: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57  _COMMIT_ATOMIC_W
d9c0: 52 49 54 45 20 20 20 20 33 32 0a 23 64 65 66 69  RITE    32.#defi
d9d0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d9e0: 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f  ROLLBACK_ATOMIC_
d9f0: 57 52 49 54 45 20 20 33 33 0a 23 64 65 66 69 6e  WRITE  33.#defin
da00: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
da10: 4f 43 4b 5f 54 49 4d 45 4f 55 54 20 20 20 20 20  OCK_TIMEOUT     
da20: 20 20 20 20 20 20 33 34 0a 23 64 65 66 69 6e 65        34.#define
da30: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41   SQLITE_FCNTL_DA
da40: 54 41 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20  TA_VERSION      
da50: 20 20 20 20 20 33 35 0a 0a 2f 2a 20 64 65 70 72       35../* depr
da60: 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a  ecated names */.
da70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
da80: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
da90: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
daa0: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
dab0: 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c  FILE.#define SQL
dac0: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
dad0: 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54  YFILE      SQLIT
dae0: 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b  E_FCNTL_SET_LOCK
daf0: 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e  PROXYFILE.#defin
db00: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
db10: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
db20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53  SQLITE_FCNTL_LAS
db30: 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20  T_ERRNO.../*.** 
db40: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
db50: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
db60: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
db70: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
db80: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
db90: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
dba0: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
dbb0: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
dbc0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
dbd0: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
dbe0: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
dbf0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
dc00: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
dc10: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
dc20: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
dc30: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
dc40: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
dc50: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
dc60: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
dc70: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
dc80: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
dc90: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
dca0: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
dcb0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
dcc0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
dcd0: 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73 69  Loadable Extensi
dce0: 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41  on Thunk.**.** A
dcf0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
dd00: 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f 61  opaque sqlite3_a
dd10: 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 75  pi_routines stru
dd20: 63 74 75 72 65 20 69 73 20 70 61 73 73 65 64 20  cture is passed 
dd30: 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20  as.** the third 
dd40: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e 74  parameter to ent
dd50: 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f  ry points of [lo
dd60: 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e  adable extension
dd70: 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 72  s].  This.** str
dd80: 75 63 74 75 72 65 20 6d 75 73 74 20 62 65 20 74  ucture must be t
dd90: 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64 65  ypedefed in orde
dda0: 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  r to work around
ddb0: 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e   compiler warnin
ddc0: 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c  gs.** on some pl
ddd0: 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65  atforms..*/.type
dde0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
ddf0: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20  e3_api_routines 
de00: 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74  sqlite3_api_rout
de10: 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ines;../*.** CAP
de20: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
de30: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
de40: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
de50: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
de60: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
de70: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
de80: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
de90: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
dea0: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
deb0: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
dec0: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
ded0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
dee0: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
def0: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
df00: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
df10: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
df20: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
df30: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
df40: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
df50: 56 46 53 20 69 6e 74 65 72 66 61 63 65 20 69 73  VFS interface is
df60: 20 73 6f 6d 65 74 69 6d 65 73 20 65 78 74 65 6e   sometimes exten
df70: 64 65 64 20 62 79 20 61 64 64 69 6e 67 20 6e 65  ded by adding ne
df80: 77 20 6d 65 74 68 6f 64 73 20 6f 6e 74 6f 0a 2a  w methods onto.*
df90: 2a 20 74 68 65 20 65 6e 64 2e 20 20 45 61 63 68  * the end.  Each
dfa0: 20 74 69 6d 65 20 73 75 63 68 20 61 6e 20 65 78   time such an ex
dfb0: 74 65 6e 73 69 6f 6e 20 6f 63 63 75 72 73 2c 20  tension occurs, 
dfc0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
dfd0: 6c 64 0a 2a 2a 20 69 73 20 69 6e 63 72 65 6d 65  ld.** is increme
dfe0: 6e 74 65 64 2e 20 20 54 68 65 20 69 56 65 72 73  nted.  The iVers
dff0: 69 6f 6e 20 76 61 6c 75 65 20 73 74 61 72 74 65  ion value starte
e000: 64 20 6f 75 74 20 61 73 20 31 20 69 6e 0a 2a 2a  d out as 1 in.**
e010: 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e   SQLite [version
e020: 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b 64 61 74 65   3.5.0] on [date
e030: 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74 68 65 6e 20  of:3.5.0], then 
e040: 69 6e 63 72 65 61 73 65 64 20 74 6f 20 32 0a 2a  increased to 2.*
e050: 2a 20 77 69 74 68 20 53 51 4c 69 74 65 20 5b 76  * with SQLite [v
e060: 65 72 73 69 6f 6e 20 33 2e 37 2e 30 5d 20 6f 6e  ersion 3.7.0] on
e070: 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e 30 5d 2c   [dateof:3.7.0],
e080: 20 61 6e 64 20 74 68 65 6e 20 69 6e 63 72 65 61   and then increa
e090: 73 65 64 0a 2a 2a 20 74 6f 20 33 20 77 69 74 68  sed.** to 3 with
e0a0: 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e   SQLite [version
e0b0: 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b 64 61 74 65   3.7.6] on [date
e0c0: 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20 41 64 64 69  of:3.7.6].  Addi
e0d0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a  tional fields.**
e0e0: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
e0f0: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
e100: 76 66 73 20 6f 62 6a 65 63 74 20 61 6e 64 20 74  vfs object and t
e110: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
e120: 65 0a 2a 2a 20 6d 61 79 20 69 6e 63 72 65 61 73  e.** may increas
e130: 65 20 61 67 61 69 6e 20 69 6e 20 66 75 74 75 72  e again in futur
e140: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
e150: 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  Lite..** Note th
e160: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65  at the structure
e170: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
e180: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68  e3_vfs object ch
e190: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61  anges in the tra
e1a0: 6e 73 69 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20  nsition from.** 
e1b0: 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20  SQLite [version 
e1c0: 33 2e 35 2e 39 5d 20 74 6f 20 5b 76 65 72 73 69  3.5.9] to [versi
e1d0: 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e 20 5b 64 61  on 3.6.0] on [da
e1e0: 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a 2a 2a 20 61  teof:3.6.0].** a
e1f0: 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73  nd yet the iVers
e200: 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f  ion field was no
e210: 74 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  t modified..**.*
e220: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
e230: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
e240: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
e250: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
e260: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
e270: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
e280: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
e290: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
e2a0: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
e2b0: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
e2c0: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
e2d0: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  d sqlite3_vfs ob
e2e0: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f  jects are kept o
e2f0: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
e300: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
e310: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
e320: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
e330: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
e340: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
e350: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
e360: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
e370: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
e380: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
e390: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
e3a0: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
e3b0: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
e3c0: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20  ches the list.  
e3d0: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c  Neither the appl
e3e0: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72  ication code nor
e3f0: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c   the VFS.** impl
e400: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
e410: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20  d use the pNext 
e420: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
e430: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
e440: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
e450: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
e460: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  vfs.** structure
e470: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
e480: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
e490: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
e4a0: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
e4b0: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
e4c0: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
e4d0: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
e4e0: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
e4f0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
e500: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
e510: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
e520: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
e530: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
e540: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
e550: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
e560: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
e570: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
e580: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
e590: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
e5a0: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
e5b0: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
e5c0: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
e5d0: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
e5e0: 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74  Open]].** ^SQLit
e5f0: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
e600: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  t the zFilename 
e610: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
e620: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  en.** is either 
e630: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
e640: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  r string obtaine
e650: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50  d.** from xFullP
e660: 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61  athname() with a
e670: 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69  n optional suffi
e680: 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  x added..** ^If 
e690: 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65  a suffix is adde
e6a0: 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61  d to the zFilena
e6b0: 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74  me parameter, it
e6c0: 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74   will.** consist
e6d0: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22   of a single "-"
e6e0: 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f   character follo
e6f0: 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74  wed by no more t
e700: 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e  han.** 11 alphan
e710: 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d  umeric and/or "-
e720: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
e730: 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72   ^SQLite further
e740: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
e750: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
e760: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
e770: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
e780: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
e790: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20  called. Because 
e7a0: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
e7b0: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65  sentence,.** the
e7c0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
e7d0: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65  can safely store
e7e0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
e7f0: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
e800: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
e810: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
e820: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
e830: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  on..** If the zF
e840: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
e850: 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20  r to xOpen is a 
e860: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
e870: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20  n xOpen.** must 
e880: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74  invent its own t
e890: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f  emporary name fo
e8a0: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68  r the file.  ^Wh
e8b0: 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78  enever the .** x
e8c0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
e8d0: 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69  er is NULL it wi
e8e0: 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63  ll also be the c
e8f0: 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ase that the.** 
e900: 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
e910: 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51  will include [SQ
e920: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
e930: 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20  ONCLOSE]..**.** 
e940: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
e950: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e  nt to xOpen() in
e960: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20  cludes all bits 
e970: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c  set in.** the fl
e980: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
e990: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
e9a0: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c  ()].  Or if [sql
e9b0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
e9c0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
e9d0: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74  16()] is used, t
e9e0: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64  hen flags includ
e9f0: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b  es at least.** [
ea00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
ea10: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
ea20: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a  _OPEN_CREATE]. .
ea30: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70  ** If xOpen() op
ea40: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d  ens a file read-
ea50: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74  only then it set
ea60: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a  s *pOutFlags to.
ea70: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ** include [SQLI
ea80: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
ea90: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  ].  Other bits i
eaa0: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
eab0: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e   be set..**.** ^
eac0: 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73  (SQLite will als
ead0: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
eae0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
eaf0: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
eb00: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
eb10: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
eb20: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
eb30: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
eb40: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
eb50: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
eb60: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
eb70: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
eb80: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
eb90: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
eba0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
ebb0: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
ebc0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ebd0: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
ebe0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
ebf0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
ec00: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
ec10: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
ec20: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
ec30: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
ec40: 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29  N_WAL].** </ul>)
ec50: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  ^.**.** The file
ec60: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
ec70: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
ec80: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
ec90: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
eca0: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
ecb0: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
ecc0: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
ecd0: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
ece0: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
ecf0: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
ed00: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
ed10: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
ed20: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
ed30: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
ed40: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
ed50: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
ed60: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
ed70: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
ed80: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
ed90: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
eda0: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
edb0: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
edc0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
edd0: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
ede0: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
edf0: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
ee00: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
ee10: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
ee20: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
ee30: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
ee40: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
ee50: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
ee60: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
ee70: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
ee80: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
ee90: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
eea0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
eeb0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
eec0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
eed0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
eee0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
eef0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
ef00: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
ef10: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
ef20: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
ef30: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
ef40: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
ef50: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
ef60: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68   is closed.  ^Th
ef70: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
ef80: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
ef90: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72   will be set for
efa0: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20   TEMP databases 
efb0: 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61  and their journa
efc0: 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a  ls, transient.**
efd0: 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20   databases, and 
efe0: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a  subjournals..**.
eff0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
f000: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20  OPEN_EXCLUSIVE] 
f010: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75  flag is always u
f020: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69  sed in conjuncti
f030: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
f040: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
f050: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20  TE] flag, which 
f060: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c  are both directl
f070: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74  y.** analogous t
f080: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64  o the O_EXCL and
f090: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f   O_CREAT flags o
f0a0: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e  f the POSIX open
f0b0: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20  ().** API.  The 
f0c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
f0d0: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e  USIVE flag, when
f0e0: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65   paired with the
f0f0: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e   .** SQLITE_OPEN
f100: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64  _CREATE, is used
f110: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
f120: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c  t file should al
f130: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74  ways.** be creat
f140: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20  ed, and that it 
f150: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69  is an error if i
f160: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73  t already exists
f170: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f  ..** It is <i>no
f180: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e  t</i> used to in
f190: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20  dicate the file 
f1a0: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
f1b0: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69   .** for exclusi
f1c0: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a  ve access..**.**
f1d0: 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46   ^At least szOsF
f1e0: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  ile bytes of mem
f1f0: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  ory are allocate
f200: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74  d by SQLite.** t
f210: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c  o hold the  [sql
f220: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
f230: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
f240: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
f250: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20  ment to xOpen.  
f260: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
f270: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74   does not have t
f280: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68  o.** allocate th
f290: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20  e structure; it 
f2a0: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c  should just fill
f2b0: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68   it in.  Note th
f2c0: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20  at.** the xOpen 
f2d0: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20  method must set 
f2e0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
f2f0: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74  .pMethods to eit
f300: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b  her.** a valid [
f310: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
f320: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f  ds] object or to
f330: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75   NULL.  xOpen mu
f340: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76  st do.** this ev
f350: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66  en if the open f
f360: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78  ails.  SQLite ex
f370: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73  pects that the s
f380: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
f390: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20  hods.** element 
f3a0: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66  will be valid af
f3b0: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e  ter xOpen return
f3c0: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  s regardless of 
f3d0: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f  the success.** o
f3e0: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65  r failure of the
f3f0: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a   xOpen call..**.
f400: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
f410: 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54  .xAccess]].** ^T
f420: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
f430: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
f440: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
f450: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
f460: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
f470: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
f480: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
f490: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
f4a0: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
f4b0: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
f4c0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
f4d0: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
f4e0: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
f4f0: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
f500: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
f510: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
f520: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
f530: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
f540: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
f550: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
f560: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
f570: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
f580: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
f590: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
f5a0: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63  hname.  The exac
f5b0: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
f5c0: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
f5d0: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
f5e0: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
f5f0: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49  both  methods. I
f600: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
f610: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61  fer.** is not la
f620: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c  rge enough, [SQL
f630: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68  ITE_CANTOPEN] sh
f640: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
f650: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a  . Since this is.
f660: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  ** handled as a 
f670: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
f680: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65  QLite, vfs imple
f690: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
f6a0: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f  d endeavor.** to
f6b0: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
f6c0: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e   setting mxPathn
f6d0: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69  ame to a suffici
f6e0: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75  ently large valu
f6f0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61  e..**.** The xRa
f700: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
f710: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69  ep(), xCurrentTi
f720: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  me(), and xCurre
f730: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a  ntTimeInt64().**
f740: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
f750: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70  not strictly a p
f760: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73  art of the files
f770: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20  ystem, but they 
f780: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20  are.** included 
f790: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63  in the VFS struc
f7a0: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74  ture for complet
f7b0: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52  eness..** The xR
f7c0: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63  andomness() func
f7d0: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f  tion attempts to
f7e0: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62   return nBytes b
f7f0: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d  ytes.** of good-
f800: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
f810: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54  ss into zOut.  T
f820: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
f830: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c  is.** the actual
f840: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
f850: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f   of randomness o
f860: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  btained..** The 
f870: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
f880: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69  causes the calli
f890: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
f8a0: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
f8b0: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
f8c0: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
f8d0: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72  ven.  ^The xCurr
f8e0: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74  entTime().** met
f8f0: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75  hod returns a Ju
f900: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20  lian Day Number 
f910: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
f920: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73  date and time as
f930: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70  .** a floating p
f940: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e  oint value..** ^
f950: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
f960: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72  Int64() method r
f970: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e  eturns, as an in
f980: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61  teger, the Julia
f990: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20  n.** Day Number 
f9a0: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36  multiplied by 86
f9b0: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
f9c0: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
f9d0: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
f9e0: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
f9f0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
fa00: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
fa10: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
fa20: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
fa30: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
fa40: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
fa50: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
fa60: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
fa70: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
fa80: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
fa90: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
faa0: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
fab0: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
fac0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
fad0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
fae0: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
faf0: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
fb00: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xSetSystemCall()
fb10: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  , xGetSystemCall
fb20: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73  (), and xNestSys
fb30: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66  temCall() interf
fb40: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
fb50: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69  used by the SQLi
fb60: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20  te core.  These 
fb70: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61  optional interfa
fb80: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
fb90: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65  .** by some VFSe
fba0: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20  s to facilitate 
fbb0: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56  testing of the V
fbc0: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72  FS code. By over
fbd0: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65  riding .** syste
fbe0: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e  m calls with fun
fbf0: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73  ctions under its
fc00: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74   control, a test
fc10: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20   program can.** 
fc20: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20  simulate faults 
fc30: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74  and error condit
fc40: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20  ions that would 
fc50: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66  otherwise be dif
fc60: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70  ficult.** or imp
fc70: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63  ossible to induc
fc80: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73  e.  The set of s
fc90: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74  ystem calls that
fca0: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
fcb0: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f  en.** varies fro
fcc0: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f  m one VFS to ano
fcd0: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f  ther, and from o
fce0: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ne version of th
fcf0: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68  e same VFS to th
fd00: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
fd10: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
fd20: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  e these interfac
fd30: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61  es must be prepa
fd40: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f  red for any.** o
fd50: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69  r all of these i
fd60: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20  nterfaces to be 
fd70: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69  NULL or for thei
fd80: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68  r behavior to ch
fd90: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65  ange.** from one
fda0: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20   release to the 
fdb0: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
fdc0: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74  ons must not att
fdd0: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a  empt to access.*
fde0: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d  * any of these m
fdf0: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56  ethods if the iV
fe00: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46  ersion of the VF
fe10: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33  S is less than 3
fe20: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
fe30: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
fe40: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70  sqlite3_vfs;.typ
fe50: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
fe60: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
fe70: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73  (void);.struct s
fe80: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
fe90: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
fea0: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
feb0: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
fec0: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33  ber (currently 3
fed0: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
fee0: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
fef0: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
ff00: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
ff10: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
ff20: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
ff30: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
ff40: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
ff50: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
ff60: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
ff70: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
ff80: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
ff90: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
ffa0: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
ffb0: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
ffc0: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
ffd0: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
ffe0: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
fff0: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
10000 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
10010 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
10020 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
10030 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
10040 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
10050 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
10060 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
10070 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
10080 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
10090 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
100a0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
100b0 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
100c0 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
100d0 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
100e0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
100f0 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
10100 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
10110 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
10120 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
10130 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
10140 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
10150 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
10160 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
10170 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
10180 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
10190 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
101a0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
101b0 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
101c0 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
101d0 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
101e0 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
101f0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
10200 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
10210 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
10220 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
10230 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
10240 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
10250 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
10260 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
10270 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
10280 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
10290 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
102a0 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
102b0 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
102c0 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
102d0 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
102e0 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
102f0 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
10300 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
10310 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
10320 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
10330 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
10340 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
10350 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
10360 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
10370 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
10380 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
10390 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72   */.  int (*xCur
103a0 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73  rentTimeInt64)(s
103b0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c  qlite3_vfs*, sql
103c0 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20  ite3_int64*);.  
103d0 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
103e0 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
103f0 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20   versions 1 and 
10400 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  2 of the sqlite_
10410 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
10420 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65   Those below are
10430 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61   for version 3 a
10440 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f  nd greater..  */
10450 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73  .  int (*xSetSys
10460 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
10470 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
10480 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
10490 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a  3_syscall_ptr);.
104a0 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c    sqlite3_syscal
104b0 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74  l_ptr (*xGetSyst
104c0 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
104d0 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
104e0 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73   *zName);.  cons
104f0 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53  t char *(*xNextS
10500 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
10510 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
10520 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f  har *zName);.  /
10530 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
10540 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
10550 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75  versions 1 throu
10560 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69  gh 3 of the sqli
10570 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
10580 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   ** New fields m
10590 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
105a0 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
105b0 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
105c0 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
105d0 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
105e0 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
105f0 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  . .  */.};../*.*
10600 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
10610 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
10620 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  s VFS method.**.
10630 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
10640 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
10650 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
10660 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
10670 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
10680 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
10690 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
106a0 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  t.  They determi
106b0 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
106c0 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
106d0 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
106e0 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
106f0 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
10700 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
10710 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
10720 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
10730 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
10740 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
10750 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
10760 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
10770 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
10780 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
10790 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72  er the named dir
107a0 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72  ectory is both r
107b0 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
107c0 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65  able.** (in othe
107d0 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65  r words, if file
107e0 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20  s can be added, 
107f0 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e  removed, and ren
10800 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74  amed within.** t
10810 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a  he directory)..*
10820 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43  * The SQLITE_ACC
10830 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f  ESS_READWRITE co
10840 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e  nstant is curren
10850 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79  tly used only by
10860 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74   the.** [temp_st
10870 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
10880 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68  agma], though th
10890 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20  is could change 
108a0 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
108b0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
108c0 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
108d0 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
108e0 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
108f0 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
10900 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
10910 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51  eadable.  The SQ
10920 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
10930 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20   constant is.** 
10940 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64  currently unused
10950 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68  , though it migh
10960 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66  t be used in a f
10970 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
10980 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23  .** SQLite..*/.#
10990 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
109a0 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
109b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
109c0 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
109d0 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20   1   /* Used by 
109e0 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72  PRAGMA temp_stor
109f0 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23  e_directory */.#
10a00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
10a10 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
10a20 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a     /* Unused */.
10a30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10a40 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
10a50 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68  ShmLock VFS meth
10a60 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
10a70 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
10a80 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69   define the vari
10a90 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72  ous locking oper
10aa0 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65  ations.** allowe
10ab0 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63  d by the xShmLoc
10ac0 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c  k method of [sql
10ad0 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
10ae0 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  .  The.** follow
10af0 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79  ing are the only
10b00 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69   legal combinati
10b10 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20  ons of flags to 
10b20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20  the.** xShmLock 
10b30 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
10b40 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
10b50 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
10b60 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
10b70 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
10b80 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
10b90 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
10ba0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
10bb0 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
10bc0 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
10bd0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
10be0 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
10bf0 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
10c00 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
10c10 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20  When unlocking, 
10c20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20  the same SHARED 
10c30 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61  or EXCLUSIVE fla
10c40 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69  g must be suppli
10c50 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76  ed as.** was giv
10c60 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73  en on the corres
10c70 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a  ponding lock.  .
10c80 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
10c90 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72  ck method can tr
10ca0 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
10cb0 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48   unlocked and SH
10cc0 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65  ARED or.** betwe
10cd0 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
10ce0 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63  EXCLUSIVE.  It c
10cf0 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e  annot transition
10d00 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a   between SHARED.
10d10 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ** and EXCLUSIVE
10d20 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
10d30 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20  ITE_SHM_UNLOCK  
10d40 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
10d50 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20  QLITE_SHM_LOCK  
10d60 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
10d70 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
10d80 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69  ED       4.#defi
10d90 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58  ne SQLITE_SHM_EX
10da0 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a  CLUSIVE    8../*
10db0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
10dc0 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69  ximum xShmLock i
10dd0 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ndex.**.** The x
10de0 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
10df0 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
10e00 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76  thods] may use v
10e10 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
10e20 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65   0 and this uppe
10e30 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22  r bound as its "
10e40 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74  offset" argument
10e50 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
10e60 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  core will never 
10e70 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69  attempt to acqui
10e80 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a  re or release a.
10e90 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20  ** lock outside 
10ea0 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f  of this range.*/
10eb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10ec0 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20  SHM_NLOCK       
10ed0 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   8.../*.** CAPI3
10ee0 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
10ef0 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
10f00 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
10f10 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10f20 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
10f30 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
10f40 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e  Lite library.  ^
10f50 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
10f60 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
10f70 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
10f80 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
10f90 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
10fa0 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
10fb0 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73  alize()..** Thes
10fc0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
10fd0 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69  esigned to aid i
10fe0 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  n process initia
10ff0 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  lization and.** 
11000 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65  shutdown on embe
11010 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57  dded systems.  W
11020 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69  orkstation appli
11030 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a  cations using.**
11040 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79   SQLite normally
11050 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20   do not need to 
11060 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66  invoke either of
11070 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
11080 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
11090 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
110a0 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
110b0 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
110c0 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
110d0 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
110e0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
110f0 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
11100 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
11110 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
11120 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
11130 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
11140 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
11150 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
11160 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
11170 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11180 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20  n().  ^(Only an 
11190 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a  effective call.*
111a0 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69  * of sqlite3_ini
111b0 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61  tialize() does a
111c0 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ny initializatio
111d0 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  n.  All other ca
111e0 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c  lls.** are harml
111f0 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
11200 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
11210 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11220 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
11230 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
11240 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61   the first.** ca
11250 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
11260 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74  utdown() since t
11270 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
11280 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e  initialize().  ^
11290 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65  (Only.** an effe
112a0 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
112b0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
112c0 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
112d0 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
112e0 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63  ll other valid c
112f0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
11300 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68  shutdown() are h
11310 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
11320 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ^.**.** The sqli
11330 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11340 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
11350 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71  readsafe, but sq
11360 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11370 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65  .** is not.  The
11380 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11390 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75  n() interface mu
113a0 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  st only be calle
113b0 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67  d from a.** sing
113c0 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20  le thread.  All 
113d0 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
113e0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74  onnections] must
113f0 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61   be closed and a
11400 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ll.** other SQLi
11410 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73  te resources mus
11420 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  t be deallocated
11430 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69   prior to invoki
11440 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68  ng.** sqlite3_sh
11450 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  utdown()..**.** 
11460 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
11470 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69  gs, ^sqlite3_ini
11480 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69  tialize() will i
11490 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
114a0 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
114b0 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33  ilarly, ^sqlite3
114c0 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77  _shutdown().** w
114d0 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ill invoke sqlit
114e0 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
114f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
11500 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
11510 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
11520 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
11530 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20  ess..** ^If for 
11540 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c  some reason, sql
11550 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11560 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69  ) is unable to i
11570 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65  nitialize.** the
11580 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70   library (perhap
11590 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  s it is unable t
115a0 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65  o allocate a nee
115b0 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63  ded resource suc
115c0 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29  h.** as a mutex)
115d0 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b   it returns an [
115e0 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
115f0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
11600 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  K]..**.** ^The s
11610 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11620 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
11630 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
11640 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
11650 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
11660 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
11670 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
11680 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
11690 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
116a0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
116b0 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
116c0 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
116d0 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
116e0 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
116f0 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
11700 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
11710 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
11720 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
11730 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
11740 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
11750 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
11760 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
11770 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e  d.** already.  ^
11780 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
11790 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
117a0 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
117b0 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a  OMIT_AUTOINIT].*
117c0 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
117d0 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
117e0 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
117f0 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
11800 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
11810 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
11820 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
11830 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
11840 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
11850 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
11860 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
11870 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
11880 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
11890 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
118a0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
118b0 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
118c0 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
118d0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
118e0 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
118f0 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
11900 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
11910 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
11920 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
11930 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
11940 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
11950 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
11960 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
11970 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
11980 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11990 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  ith [SQLITE_OMIT
119a0 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74  _AUTOINIT] might
119b0 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
119c0 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
119d0 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
119e0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
119f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
11a00 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
11a10 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
11a20 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
11a30 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
11a40 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
11a50 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
11a60 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
11a70 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
11a80 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
11a90 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
11aa0 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
11ab0 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
11ac0 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
11ad0 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
11ae0 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
11af0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
11b00 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
11b10 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
11b20 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
11b30 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
11b40 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
11b50 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
11b60 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
11b70 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
11b80 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
11b90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11ba0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
11bb0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
11bc0 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
11bd0 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
11be0 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
11bf0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
11c00 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
11c10 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
11c20 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
11c30 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11c40 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
11c50 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
11c60 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
11c70 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
11c80 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
11c90 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
11ca0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11cb0 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
11cc0 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
11cd0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
11ce0 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
11cf0 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
11d00 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
11d10 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
11d20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
11d30 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
11d40 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
11d50 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
11d60 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64  d for Unix, Wind
11d70 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a  ows, or OS/2..**
11d80 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75   When [custom bu
11d90 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72  ilds | built for
11da0 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
11db0 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20  ].** (using the 
11dc0 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52  [SQLITE_OS_OTHER
11dd0 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =1] compile-time
11de0 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20  .** option) the 
11df0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
11e00 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62   supply a suitab
11e10 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
11e20 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  n for.** sqlite3
11e30 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
11e40 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
11e50 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    An application
11e60 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70  -supplied.** imp
11e70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
11e80 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
11e90 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
11ea0 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74  nd().** must ret
11eb0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
11ec0 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
11ed0 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
11ee0 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
11ef0 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73  ailure..*/.int s
11f00 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11f10 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  e(void);.int sql
11f20 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f  ite3_shutdown(vo
11f30 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
11f40 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
11f50 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  int sqlite3_os_e
11f60 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  nd(void);../*.**
11f70 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
11f80 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74  guring The SQLit
11f90 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
11fa0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
11fb0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
11fc0 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67  s used to make g
11fd0 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74  lobal configurat
11fe0 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
11ff0 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  o SQLite in orde
12000 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65  r to tune SQLite
12010 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
12020 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65   needs of.** the
12030 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54   application.  T
12040 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  he default confi
12050 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f  guration is reco
12060 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74  mmended for most
12070 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
12080 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75   and so this rou
12090 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20  tine is usually 
120a0 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20  not necessary.  
120b0 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65  It is.** provide
120c0 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72  d to support rar
120d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77  e applications w
120e0 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64  ith unusual need
120f0 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20  s..**.** <b>The 
12100 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12110 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
12120 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68  t threadsafe. Th
12130 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
12140 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61   must ensure tha
12150 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
12160 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
12170 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
12180 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
12190 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
121a0 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c  g() is running.<
121b0 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  /b>.**.** The sq
121c0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
121d0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20  nterface.** may 
121e0 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
121f0 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
12200 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
12210 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
12220 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
12230 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
12240 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
12250 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49  utdown()]..** ^I
12260 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  f sqlite3_config
12270 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74  () is called aft
12280 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  er [sqlite3_init
12290 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65  ialize()] and be
122a0 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fore.** [sqlite3
122b0 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65  _shutdown()] the
122c0 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  n it will return
122d0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
122e0 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
122f0 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f  , that ^sqlite3_
12300 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
12310 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
12320 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
12330 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
12340 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
12350 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
12360 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
12370 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
12380 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
12390 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
123a0 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74  r.** [configurat
123b0 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74  ion option] that
123c0 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77   determines.** w
123d0 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20  hat property of 
123e0 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20  SQLite is to be 
123f0 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62  configured.  Sub
12400 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
12410 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64  s.** vary depend
12420 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66  ing on the [conf
12430 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12440 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
12450 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
12460 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67  * ^When a config
12470 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
12480 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63  s set, sqlite3_c
12490 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20  onfig() returns 
124a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20  [SQLITE_OK]..** 
124b0 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69  ^If the option i
124c0 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c  s unknown or SQL
124d0 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
124e0 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a   set the option.
124f0 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  ** then this rou
12500 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e  tine returns a n
12510 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
12520 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ode]..*/.int sql
12530 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c  ite3_config(int,
12540 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
12550 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
12560 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
12570 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
12580 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
12590 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
125a0 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
125b0 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
125c0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
125d0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
125e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
125f0 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
12600 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
12610 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
12620 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
12630 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
12640 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
12650 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
12660 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
12670 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
12680 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
12690 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
126a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
126b0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
126c0 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
126d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
126e0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
126f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
12700 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
12710 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
12720 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
12730 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
12740 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12750 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
12760 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
12770 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
12780 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
12790 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
127a0 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
127b0 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
127c0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
127d0 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
127e0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
127f0 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
12800 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
12810 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
12820 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
12830 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
12840 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
12850 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
12860 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
12870 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
12880 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
12890 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
128a0 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
128b0 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
128c0 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
128d0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
128e0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
128f0 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
12900 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
12910 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
12920 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
12930 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
12940 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
12950 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
12960 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
12970 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
12980 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
12990 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
129a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
129b0 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
129c0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
129d0 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
129e0 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
129f0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
12a00 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
12a10 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
12a20 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
12a30 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
12a40 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
12a50 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
12a60 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
12a70 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
12a80 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
12a90 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
12aa0 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
12ab0 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
12ac0 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
12ad0 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
12ae0 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
12af0 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
12b00 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
12b10 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
12b20 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
12b30 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
12b40 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
12b50 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
12b60 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
12b70 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
12b80 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
12b90 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
12ba0 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
12bb0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
12bc0 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
12bd0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
12be0 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
12bf0 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
12c00 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
12c10 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
12c20 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
12c30 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
12c40 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
12c50 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
12c60 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
12c70 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
12c80 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
12c90 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
12ca0 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
12cb0 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
12cc0 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
12cd0 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
12ce0 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
12cf0 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
12d00 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
12d10 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
12d20 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
12d30 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
12d40 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
12d50 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
12d60 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
12d70 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
12d80 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
12d90 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
12da0 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
12db0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
12dc0 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
12dd0 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
12de0 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
12df0 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
12e00 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
12e10 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
12e20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
12e30 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
12e40 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
12e50 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
12e60 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
12e70 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
12e80 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
12e90 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
12ea0 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
12eb0 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
12ec0 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
12ed0 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
12ee0 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
12ef0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
12f00 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
12f10 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
12f20 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
12f30 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
12f40 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
12f50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
12f60 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
12f70 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
12f80 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
12f90 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
12fa0 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
12fb0 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
12fc0 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
12fd0 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
12fe0 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
12ff0 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
13000 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
13010 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
13020 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
13030 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
13040 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
13050 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
13060 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
13070 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
13080 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
13090 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
130a0 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
130b0 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
130c0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
130d0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
130e0 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
130f0 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
13100 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
13110 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
13120 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
13130 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
13140 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
13150 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
13160 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
13170 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
13180 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
13190 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
131a0 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
131b0 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
131c0 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
131d0 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
131e0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
131f0 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
13200 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
13210 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
13220 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
13230 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65  ASTER] mutex whe
13240 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  n it invokes.** 
13250 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
13260 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d  , so the xInit m
13270 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62  ethod need not b
13280 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  e threadsafe.  T
13290 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20  he.** xShutdown 
132a0 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63  method is only c
132b0 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  alled from [sqli
132c0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
132d0 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  so it does.** no
132e0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72  t need to be thr
132f0 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20  eadsafe either. 
13300 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d   For all other m
13310 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a  ethods, SQLite.*
13320 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  * holds the [SQL
13330 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
13340 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c  _MEM] mutex as l
13350 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53  ong as the.** [S
13360 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
13370 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72  STATUS] configur
13380 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
13390 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68  turned on (which
133a0 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66  .** it is by def
133b0 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65  ault) and so the
133c0 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74   methods are aut
133d0 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61  omatically seria
133e0 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65  lized..** Howeve
133f0 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f  r, if [SQLITE_CO
13400 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
13410 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  is disabled, the
13420 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d  n the other.** m
13430 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74  ethods must be t
13440 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73  hreadsafe or els
13450 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e  e make their own
13460 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f   arrangements fo
13470 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69  r.** serializati
13480 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
13490 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
134a0 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20  ke xInit() more 
134b0 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75  than once withou
134c0 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67  t an intervening
134d0 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75  .** call to xShu
134e0 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65  tdown()..*/.type
134f0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
13500 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
13510 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
13520 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
13530 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
13540 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
13550 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
13560 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
13570 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
13580 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
13590 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
135a0 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
135b0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
135c0 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
135d0 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
135e0 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
135f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
13600 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
13610 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
13620 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
13630 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
13640 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
13650 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
13660 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
13670 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
13680 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
13690 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
136a0 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
136b0 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
136c0 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
136d0 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
136e0 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
136f0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
13700 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
13710 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
13720 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
13730 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
13740 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
13750 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
13760 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
13770 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
13780 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
13790 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45  on Options.** KE
137a0 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75  YWORDS: {configu
137b0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a  ration option}.*
137c0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
137d0 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
137e0 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
137f0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13800 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
13810 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
13820 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
13830 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
13840 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
13850 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
13860 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13870 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
13880 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
13890 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
138a0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
138b0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
138c0 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
138d0 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
138e0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
138f0 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
13900 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
13910 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13920 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
13930 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
13940 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
13950 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
13960 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
13970 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
13980 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
13990 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
139a0 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
139b0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
139c0 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
139d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
139e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
139f0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d  G_SINGLETHREAD]]
13a00 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13a10 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
13a20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
13a30 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
13a40 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
13a50 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
13a60 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
13a70 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
13a80 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
13a90 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
13aa0 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
13ab0 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
13ac0 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
13ad0 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
13ae0 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
13af0 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
13b00 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
13b10 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
13b20 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
13b30 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13b40 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
13b50 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
13b60 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
13b70 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
13b80 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
13b90 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
13ba0 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
13bb0 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
13bc0 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
13bd0 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
13be0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
13bf0 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
13c00 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
13c10 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
13c20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
13c30 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
13c40 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13c50 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
13c60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
13c70 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  TITHREAD]] <dt>S
13c80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
13c90 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
13ca0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
13cb0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
13cc0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
13cd0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
13ce0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
13cf0 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
13d00 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
13d10 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
13d20 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
13d30 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
13d40 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
13d50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
13d60 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
13d70 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
13d80 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
13d90 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
13da0 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
13db0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
13dc0 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
13dd0 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
13de0 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
13df0 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
13e00 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
13e10 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
13e20 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
13e30 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
13e40 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
13e50 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
13e60 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
13e70 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
13e80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
13e90 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
13ea0 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
13eb0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
13ec0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
13ed0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
13ee0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
13ef0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
13f00 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
13f10 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
13f20 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
13f30 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
13f40 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
13f50 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13f60 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
13f70 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
13f80 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
13f90 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
13fa0 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
13fb0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13fc0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
13fd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
13fe0 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53  RIALIZED]] <dt>S
13ff0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
14000 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
14010 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
14020 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
14030 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
14040 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
14050 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
14060 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69  mode] to Seriali
14070 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  zed. In other wo
14080 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e  rds, this option
14090 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
140a0 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
140b0 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
140c0 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
140d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
140e0 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
140f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
14100 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
14110 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
14120 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
14130 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
14140 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
14150 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
14160 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
14170 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
14180 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
14190 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
141a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
141b0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
141c0 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
141d0 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
141e0 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
141f0 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
14200 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14210 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
14220 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
14230 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
14240 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
14250 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
14260 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
14270 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
14280 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
14290 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
142a0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
142b0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
142c0 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
142d0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
142e0 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a  set the Serializ
142f0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
14300 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
14310 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
14320 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
14330 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
14340 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
14350 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
14360 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72  IALIZED configur
14370 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
14380 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14390 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
143a0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
143b0 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
143c0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
143d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
143e0 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
143f0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
14400 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61  t which is .** a
14410 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
14420 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
14430 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
14440 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
14450 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
14460 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
14470 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
14480 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
14490 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f  tion routines to
144a0 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
144b0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  e of.** the memo
144c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
144d0 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
144e0 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c  o SQLite.)^ ^SQL
144f0 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73  ite makes.** its
14500 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
14510 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74  y of the content
14520 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
14530 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
14540 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72  ructure.** befor
14550 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  e the [sqlite3_c
14560 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65  onfig()] call re
14570 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  turns.</dd>.**.*
14580 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14590 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  G_GETMALLOC]] <d
145a0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
145b0 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
145c0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
145d0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
145e0 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65  LLOC option take
145f0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
14600 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
14610 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
14620 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
14630 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
14640 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
14650 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
14660 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
14670 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
14680 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
14690 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
146a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
146b0 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
146c0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
146d0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
146e0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
146f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14700 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
14710 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
14720 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
14730 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14740 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
14750 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
14760 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
14770 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14780 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41  QLITE_CONFIG_SMA
14790 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  LL_MALLOC]] <dt>
147a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d  SQLITE_CONFIG_SM
147b0 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  ALL_MALLOC</dt>.
147c0 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
147d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c  ITE_CONFIG_SMALL
147e0 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74  _MALLOC option t
147f0 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
14800 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74 79 70 65 20  ment of.** type 
14810 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
14820 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77   as a boolean, w
14830 68 69 63 68 20 69 66 20 74 72 75 65 20 70 72 6f  hich if true pro
14840 76 69 64 65 73 20 61 20 68 69 6e 74 20 74 6f 0a  vides a hint to.
14850 2a 2a 20 53 51 4c 69 74 65 20 74 68 61 74 20 69  ** SQLite that i
14860 74 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 20 6c  t should avoid l
14870 61 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  arge memory allo
14880 63 61 74 69 6f 6e 73 20 69 66 20 70 6f 73 73 69  cations if possi
14890 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ble..** SQLite w
148a0 69 6c 6c 20 72 75 6e 20 66 61 73 74 65 72 20 69  ill run faster i
148b0 66 20 69 74 20 69 73 20 66 72 65 65 20 74 6f 20  f it is free to 
148c0 6d 61 6b 65 20 6c 61 72 67 65 20 6d 65 6d 6f 72  make large memor
148d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 0a 2a  y allocations,.*
148e0 2a 20 62 75 74 20 73 6f 6d 65 20 61 70 70 6c 69  * but some appli
148f0 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 70 72 65  cation might pre
14900 66 65 72 20 74 6f 20 72 75 6e 20 73 6c 6f 77 65  fer to run slowe
14910 72 20 69 6e 20 65 78 63 68 61 6e 67 65 20 66 6f  r in exchange fo
14920 72 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  r.** guarantees 
14930 61 62 6f 75 74 20 6d 65 6d 6f 72 79 20 66 72 61  about memory fra
14940 67 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20  gmentation that 
14950 61 72 65 20 70 6f 73 73 69 62 6c 65 20 69 66 20  are possible if 
14960 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  large.** allocat
14970 69 6f 6e 73 20 61 72 65 20 61 76 6f 69 64 65 64  ions are avoided
14980 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
14990 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e 0a 2a 2a  normally off..**
149a0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
149b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
149c0 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c  STATUS]] <dt>SQL
149d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
149e0 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
149f0 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
14a00 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f  NFIG_MEMSTATUS o
14a10 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67  ption takes sing
14a20 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
14a30 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65  ype int,.** inte
14a40 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
14a50 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
14a60 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
14a70 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
14a80 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  f.** memory allo
14a90 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
14aa0 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79  s. ^(When memory
14ab0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
14ac0 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69  istics are.** di
14ad0 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c  sabled, the foll
14ae0 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
14af0 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e  erfaces become n
14b00 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a  on-operational:.
14b10 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  **   <ul>.**   <
14b20 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
14b30 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20  ory_used()].**  
14b40 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
14b50 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
14b60 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
14b70 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
14b80 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20  limit64()].**   
14b90 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
14ba0 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  atus64()].**   <
14bb0 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
14bc0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
14bd0 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
14be0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
14bf0 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
14c00 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
14c10 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
14c20 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
14c30 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
14c40 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
14c50 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
14c60 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
14c70 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
14c80 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14c90 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64  FIG_SCRATCH]] <d
14ca0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14cb0 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
14cc0 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f  <dd> The SQLITE_
14cd0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f  CONFIG_SCRATCH o
14ce0 70 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67  ption is no long
14cf0 65 72 20 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 64  er used..** </dd
14d00 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14d10 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
14d20 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
14d30 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
14d40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
14d50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14d60 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e  PAGECACHE option
14d70 20 73 70 65 63 69 66 69 65 73 20 61 20 6d 65 6d   specifies a mem
14d80 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74  ory pool.** that
14d90 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
14da0 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
14db0 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68   page cache with
14dc0 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67   the default pag
14dd0 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
14de0 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  mentation.  .** 
14df0 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
14e00 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e  on option is a n
14e10 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c 69  o-op if an appli
14e20 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61  cation-define pa
14e30 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
14e40 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f  ementation is lo
14e50 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  aded using the [
14e60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14e70 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72  ACHE2]..** ^Ther
14e80 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
14e90 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f  ments to SQLITE_
14ea0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
14eb0 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  : A pointer to.*
14ec0 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  * 8-byte aligned
14ed0 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20   memory (pMem), 
14ee0 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
14ef0 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65   page cache line
14f00 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
14f10 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63 68  e number of cach
14f20 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20  e lines (N)..** 
14f30 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
14f40 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69  should be the si
14f50 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ze of the larges
14f60 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a  t database page.
14f70 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74  ** (a power of t
14f80 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
14f90 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73  nd 65536) plus s
14fa0 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20  ome extra bytes 
14fb0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
14fc0 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e   header.  ^The n
14fd0 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62  umber of extra b
14fe0 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74  ytes needed by t
14ff0 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a  he page header.*
15000 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  * can be determi
15010 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49 54  ned using [SQLIT
15020 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
15030 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69  HDRSZ]..** ^It i
15040 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72  s harmless, apar
15050 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65  t from the waste
15060 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72  d memory,.** for
15070 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65   the sz paramete
15080 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74  r to be larger t
15090 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20  han necessary.  
150a0 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75  The pMem.** argu
150b0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69 74  ment must be eit
150c0 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
150d0 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20  er or a pointer 
150e0 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  to an 8-byte.** 
150f0 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66  aligned block of
15100 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65   memory of at le
15110 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20  ast sz*N bytes, 
15120 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75 62  otherwise.** sub
15130 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
15140 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
15150 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73 20  * ^When pMem is 
15160 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65  not NULL, SQLite
15170 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f 20   will strive to 
15180 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  use the memory p
15190 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61  rovided.** to sa
151a0 74 69 73 66 79 20 70 61 67 65 20 63 61 63 68 65  tisfy page cache
151b0 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20   needs, falling 
151c0 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33  back to [sqlite3
151d0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a  _malloc()] if.**
151e0 20 61 20 70 61 67 65 20 63 61 63 68 65 20 6c 69   a page cache li
151f0 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74 68 61  ne is larger tha
15200 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69 66  n sz bytes or if
15210 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d   all of the pMem
15220 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65 78   buffer.** is ex
15230 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20  hausted..** ^If 
15240 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64  pMem is NULL and
15250 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20   N is non-zero, 
15260 74 68 65 6e 20 65 61 63 68 20 64 61 74 61 62 61  then each databa
15270 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
15280 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61 6c   does an initial
15290 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e   bulk allocation
152a0 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20   for page cache 
152b0 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b  memory.** from [
152c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
152d0 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f 72  ] sufficient for
152e0 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20 69   N cache lines i
152f0 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 20  f N is positive 
15300 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e  or.** of -1024*N
15310 20 62 79 74 65 73 20 69 66 20 4e 20 69 73 20 6e   bytes if N is n
15320 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20 61  egative, . ^If a
15330 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67  dditional.** pag
15340 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69  e cache memory i
15350 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20  s needed beyond 
15360 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
15370 20 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c 0a   by the initial.
15380 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  ** allocation, t
15390 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73 20  hen SQLite goes 
153a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
153b0 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c 79  oc()] separately
153c0 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64 64   for each.** add
153d0 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69  itional cache li
153e0 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ne. </dd>.**.** 
153f0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15400 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  HEAP]] <dt>SQLIT
15410 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
15420 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
15430 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
15440 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  AP option specif
15450 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
15460 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74  ory buffer .** t
15470 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
15480 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
15490 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
154a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
154b0 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f  ds.** beyond tho
154c0 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  se provided for 
154d0 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
154e0 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
154f0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
15500 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20  FIG_HEAP option 
15510 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
15520 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  e if SQLite is c
15530 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
15540 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45  either [SQLITE_E
15550 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f  NABLE_MEMSYS3] o
15560 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
15570 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65  _MEMSYS5] and re
15580 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
15590 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b  _ERROR] if invok
155a0 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
155b0 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65   ^There are thre
155c0 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53  e arguments to S
155d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
155e0 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20  P:.** An 8-byte 
155f0 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
15600 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
15610 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
15620 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
15630 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
15640 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
15650 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
15660 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
15670 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
15680 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
15690 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
156a0 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
156b0 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
156c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
156d0 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
156e0 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
156f0 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
15700 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
15710 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
15720 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
15730 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
15740 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
15750 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68  not NULL then th
15760 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
15770 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
15780 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
15790 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
157a0 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
157b0 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
157c0 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
157d0 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
157e0 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
157f0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
15800 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
15810 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
15820 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
15830 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
15840 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
15850 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
15860 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
15870 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61  t 2**12. Reasona
15880 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f  ble values.** fo
15890 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  r the minimum al
158a0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72  location size ar
158b0 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32  e 2**5 through 2
158c0 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  **8.</dd>.**.** 
158d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
158e0 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
158f0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
15900 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
15910 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15920 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61  _MUTEX option ta
15930 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
15940 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
15950 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
15960 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
15970 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
15980 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
15990 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  ure..** The argu
159a0 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61  ment specifies a
159b0 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
159c0 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
159d0 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a  nes to be used.*
159e0 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d  * in place the m
159f0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
15a00 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
15a10 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
15a20 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
15a30 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
15a40 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
15a50 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
15a60 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
15a70 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
15a80 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
15a90 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
15aa0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
15ab0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
15ac0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
15ad0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
15ae0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
15af0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
15b00 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
15b10 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
15b20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
15b30 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
15b40 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
15b50 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
15b60 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
15b70 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
15b80 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15b90 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
15ba0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
15bb0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15bc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15bd0 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
15be0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
15bf0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
15c00 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
15c10 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69  IG_GETMUTEX opti
15c20 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
15c30 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
15c40 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
15c50 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
15c60 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
15c70 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
15c80 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
15c90 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
15ca0 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
15cb0 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
15cc0 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
15cd0 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
15ce0 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
15cf0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
15d00 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
15d10 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
15d20 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
15d30 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
15d40 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
15d50 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
15d60 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
15d70 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
15d80 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
15d90 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
15da0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
15db0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
15dc0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
15dd0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
15de0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
15df0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
15e00 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
15e10 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
15e20 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
15e30 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
15e40 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
15e50 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
15e60 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
15e70 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15e80 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
15e90 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
15ea0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
15eb0 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
15ec0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15ed0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
15ee0 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
15ef0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
15f00 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
15f10 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15f20 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f  _LOOKASIDE optio
15f30 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
15f40 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
15f50 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61  mine.** the defa
15f60 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b  ult size of look
15f70 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20  aside memory on 
15f80 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63  each [database c
15f90 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  onnection]..** T
15fa0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15fb0 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
15fc0 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
15fd0 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
15fe0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
15ff0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
16000 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
16010 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
16020 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
16030 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49    ^(SQLITE_CONFI
16040 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73  G_LOOKASIDE.** s
16050 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75  ets the <i>defau
16060 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65  lt</i> lookaside
16070 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49   size. The [SQLI
16080 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
16090 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e  ASIDE].** option
160a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
160b0 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
160c0 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
160d0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
160e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
160f0 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
16100 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
16110 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
16120 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
16130 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
16140 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e  FIG_PCACHE2</dt>
16150 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
16160 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16170 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
16180 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
16190 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a  ent which is .**
161a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
161b0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
161c0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
161d0 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
161e0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
161f0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20   interface to a 
16200 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
16210 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
16220 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d  .)^.** ^SQLite m
16230 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
16240 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  he [sqlite3_pcac
16250 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
16260 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ect.</dd>.**.** 
16270 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16280 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  GETPCACHE2]] <dt
16290 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
162a0 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  ETPCACHE2</dt>.*
162b0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
162c0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
162d0 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
162e0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
162f0 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
16300 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
16310 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
16320 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
16330 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
16340 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72  s of.** the curr
16350 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ent page cache i
16360 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
16370 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
16380 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
16390 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
163a0 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  G]] <dt>SQLITE_C
163b0 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a  ONFIG_LOG</dt>.*
163c0 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54  * <dd> The SQLIT
163d0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
163e0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63  ion is used to c
163f0 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c  onfigure the SQL
16400 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65  ite.** global [e
16410 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e  rror log]..** (^
16420 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16430 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
16440 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
16450 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
16460 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
16470 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
16480 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
16490 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
164a0 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
164b0 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
164c0 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
164d0 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
164e0 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
164f0 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
16500 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
16510 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
16520 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
16530 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
16540 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
16550 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
16560 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
16570 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
16580 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
16590 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
165a0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
165b0 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
165c0 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
165d0 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
165e0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
165f0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
16600 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
16610 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
16620 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
16630 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
16640 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
16650 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
16660 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
16670 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
16680 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
16690 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
166a0 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
166b0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
166c0 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
166d0 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
166e0 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
166f0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
16700 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
16710 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
16720 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
16730 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
16740 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
16750 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
16760 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
16770 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
16780 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
16790 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
167a0 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
167b0 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
167c0 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
167d0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
167e0 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
167f0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
16800 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
16810 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
16820 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
16830 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
16840 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
16850 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
16860 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
16870 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20  TE_CONFIG_URI]] 
16880 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16890 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54  G_URI.** <dd>^(T
168a0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
168b0 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _URI option take
168c0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
168d0 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e  ent of type int.
168e0 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c  .** If non-zero,
168f0 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
16900 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
16910 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70  nabled. If the p
16920 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f  arameter is zero
16930 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61  ,.** then URI ha
16940 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
16950 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e  ly disabled.)^ ^
16960 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  If URI handling 
16970 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65  is globally.** e
16980 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65  nabled, all file
16990 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20  names passed to 
169a0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
169b0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
169c0 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
169d0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a  e3_open16()] or.
169e0 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ** specified as 
169f0 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d  part of [ATTACH]
16a00 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e   commands are in
16a10 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
16a20 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a  s, regardless.**
16a30 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
16a40 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ot the [SQLITE_O
16a50 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
16a60 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61   set when the da
16a70 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
16a80 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
16a90 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c  ^If it is global
16aa0 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c  ly disabled, fil
16ab0 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e  enames are.** on
16ac0 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ly interpreted a
16ad0 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51  s URIs if the SQ
16ae0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c  LITE_OPEN_URI fl
16af0 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
16b00 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
16b10 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
16b20 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c  ned. ^(By defaul
16b30 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  t, URI handling 
16b40 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64  is globally.** d
16b50 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66  isabled. The def
16b60 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62  ault value may b
16b70 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d  e changed by com
16b80 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a  piling with the.
16b90 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  ** [SQLITE_USE_U
16ba0 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  RI] symbol defin
16bb0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ed.)^.**.** [[SQ
16bc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
16bd0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
16be0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
16bf0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
16c00 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e  EX_SCAN.** <dd>^
16c10 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16c20 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
16c30 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b  _SCAN option tak
16c40 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65  es a single inte
16c50 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ger.** argument 
16c60 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72  which is interpr
16c70 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
16c80 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e  n in order to en
16c90 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a  able or disable.
16ca0 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  ** the use of co
16cb0 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
16cc0 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
16cd0 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79  ans in the query
16ce0 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e   optimizer..** ^
16cf0 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
16d00 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65  ing is determine
16d10 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c  d.** by the [SQL
16d20 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49  ITE_ALLOW_COVERI
16d30 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63  NG_INDEX_SCAN] c
16d40 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
16d50 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a  on, or is "on".*
16d60 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c  * if that compil
16d70 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
16d80 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65   omitted..** The
16d90 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61   ability to disa
16da0 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63  ble the use of c
16db0 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
16dc0 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
16dd0 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75  cans.** is becau
16de0 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63  se some incorrec
16df0 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79  tly coded legacy
16e00 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69   applications mi
16e10 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a  ght malfunction.
16e20 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69  ** when the opti
16e30 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  mization is enab
16e40 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20  led.  Providing 
16e50 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a  the ability to.*
16e60 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70  * disable the op
16e70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77  timization allow
16e80 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67  s the older, bug
16e90 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  gy application c
16ea0 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ode to work.** w
16eb0 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76  ithout change ev
16ec0 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65  en with newer ve
16ed0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
16ee0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
16ef0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d  _CONFIG_PCACHE]]
16f00 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16f10 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20  _GETPCACHE]].** 
16f20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16f30 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c  G_PCACHE and SQL
16f40 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
16f50 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  ACHE.** <dd> The
16f60 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f  se options are o
16f70 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75  bsolete and shou
16f80 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62  ld not be used b
16f90 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54  y new code..** T
16fa0 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64  hey are retained
16fb0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
16fc0 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74  ompatibility but
16fd0 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e   are now no-ops.
16fe0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
16ff0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
17000 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e  SQLLOG]].** <dt>
17010 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
17020 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  LLOG.** <dd>This
17030 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
17040 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c  available if sql
17050 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
17060 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
17070 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f  ITE_ENABLE_SQLLO
17080 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  G] pre-processor
17090 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20   macro defined. 
170a0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
170b0 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20  nt should.** be 
170c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66  a pointer to a f
170d0 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
170e0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
170f0 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61  lite3*,const cha
17100 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65  r*, int)..** The
17110 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62   second should b
17120 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a  e of type (void*
17130 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ). The callback 
17140 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68  is invoked by th
17150 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20  e library.** in 
17160 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63  three separate c
17170 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64  ircumstances, id
17180 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
17190 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
171a0 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
171b0 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20  rameter. If the 
171c0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
171d0 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20   is 0, then the 
171e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
171f0 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73  ion.** passed as
17200 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
17210 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65  ment has just be
17220 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74  en opened. The t
17230 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
17240 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66   points to a buf
17250 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  fer containing t
17260 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
17270 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
17280 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75  e. If the.** fou
17290 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
172a0 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c   1, then the SQL
172b0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
172c0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
172d0 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ter.** points to
172e0 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65   has just been e
172f0 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20  xecuted. Or, if 
17300 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
17310 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a  eter is 2, then.
17320 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ** the connectio
17330 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61  n being passed a
17340 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
17350 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20  ameter is being 
17360 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74  closed. The.** t
17370 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
17380 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e  s passed NULL In
17390 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20   this case.  An 
173a0 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67  example of using
173b0 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75   this.** configu
173c0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61  ration option ca
173d0 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65  n be seen in the
173e0 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22   "test_sqllog.c"
173f0 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a   source file in.
17400 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c  ** the canonical
17410 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74   SQLite source t
17420 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ree.</dd>.**.** 
17430 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
17440 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  MMAP_SIZE]].** <
17450 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17460 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64  _MMAP_SIZE.** <d
17470 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d>^SQLITE_CONFIG
17480 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73  _MMAP_SIZE takes
17490 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65   two 64-bit inte
174a0 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74  ger (sqlite3_int
174b0 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  64) values.** th
174c0 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75  at are the defau
174d0 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  lt mmap size lim
174e0 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20  it (the default 
174f0 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b  setting for.** [
17500 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
17510 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ]) and the maxim
17520 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
17530 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e  size limit..** ^
17540 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
17550 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72  ing can be overr
17560 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61  idden by each da
17570 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17580 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65  n using.** eithe
17590 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d  r the [PRAGMA mm
175a0 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64  ap_size] command
175b0 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68  , or by using th
175c0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
175d0 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
175e0 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54  le control.  ^(T
175f0 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
17600 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20  ed mmap size.** 
17610 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79  will be silently
17620 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65   truncated if ne
17630 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20  cessary so that 
17640 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65  it does not exce
17650 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  ed the.** compil
17660 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
17670 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
17680 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
17690 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
176a0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
176b0 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68  n.)^.** ^If eith
176c0 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  er argument to t
176d0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65  his option is ne
176e0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61  gative, then tha
176f0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  t argument is.**
17700 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20   changed to its 
17710 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66  compile-time def
17720 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ault..**.** [[SQ
17730 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
17740 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20  2_HEAPSIZE]].** 
17750 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
17760 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
17770 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
17780 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
17790 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e  _HEAPSIZE option
177a0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
177b0 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a  le if SQLite is.
177c0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  ** compiled for 
177d0 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65  Windows with the
177e0 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d   [SQLITE_WIN32_M
177f0 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65  ALLOC] pre-proce
17800 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65  ssor macro.** de
17810 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43  fined. ^SQLITE_C
17820 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
17830 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d  SIZE takes a 32-
17840 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
17850 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68  eger value.** th
17860 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  at specifies the
17870 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
17880 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61   the created hea
17890 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  p..**.** [[SQLIT
178a0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
178b0 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  HDRSZ]].** <dt>S
178c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
178d0 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64  CHE_HDRSZ.** <dd
178e0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
178f0 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
17900 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
17910 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
17920 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
17930 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
17940 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20  eger and writes 
17950 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
17960 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  r the number of 
17970 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70  extra.** bytes p
17980 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64  er page required
17990 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69   for each page i
179a0 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  n [SQLITE_CONFIG
179b0 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
179c0 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78  The amount of ex
179d0 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72  tra space requir
179e0 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65  ed can change de
179f0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
17a00 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67  ompiler,.** targ
17a10 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64  et platform, and
17a20 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e   SQLite version.
17a30 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
17a40 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a  CONFIG_PMASZ]].*
17a50 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
17a60 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64  FIG_PMASZ.** <dd
17a70 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
17a80 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e  FIG_PMASZ option
17a90 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
17aa0 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
17ab0 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65  ** is an unsigne
17ac0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65  d integer and se
17ad0 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20  ts the "Minimum 
17ae0 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68  PMA Size" for th
17af0 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a  e multithreaded.
17b00 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61  ** sorter to tha
17b10 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20  t integer.  The 
17b20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20  default minimum 
17b30 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20  PMA Size is set 
17b40 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
17b50 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20  E_SORTER_PMASZ] 
17b60 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
17b70 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64  ion.  New thread
17b80 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a  s are launched.*
17b90 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73  * to help with s
17ba0 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77  ort operations w
17bb0 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65  hen multithreade
17bc0 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20  d sorting.** is 
17bd0 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74  enabled (using t
17be0 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61  he [PRAGMA threa
17bf0 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64  ds] command) and
17c00 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63   the amount of c
17c10 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20  ontent.** to be 
17c20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74  sorted exceeds t
17c30 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d  he page size tim
17c40 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f  es the minimum o
17c50 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41  f the.** [PRAGMA
17c60 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74   cache_size] set
17c70 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61  ting and this va
17c80 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  lue..**.** [[SQL
17c90 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
17ca0 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c  RNL_SPILL]].** <
17cb0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17cc0 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a  _STMTJRNL_SPILL.
17cd0 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
17ce0 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
17cf0 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e 20  NL_SPILL option 
17d00 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
17d10 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
17d20 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b 73  * becomes the [s
17d30 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c  tatement journal
17d40 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20  ] spill-to-disk 
17d50 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20  threshold.  .** 
17d60 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e  [Statement journ
17d70 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69 6e  als] are held in
17d80 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74 68   memory until th
17d90 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79 74  eir size (in byt
17da0 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20 74  es).** exceeds t
17db0 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20 61  his threshold, a
17dc0 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74 68  t which point th
17dd0 65 79 20 61 72 65 20 77 72 69 74 74 65 6e 20 74  ey are written t
17de0 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66  o disk..** Or if
17df0 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20 69   the threshold i
17e00 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74 20  s -1, statement 
17e10 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c 77  journals are alw
17e20 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63 6c  ays held.** excl
17e30 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f 72  usively in memor
17e40 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e 79  y..** Since many
17e50 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e   statement journ
17e60 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d 65  als never become
17e70 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67 20   large, setting 
17e80 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68 72  the spill.** thr
17e90 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c 75  eshold to a valu
17ea0 65 20 73 75 63 68 20 61 73 20 36 34 4b 69 42 20  e such as 64KiB 
17eb0 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64 75  can greatly redu
17ec0 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  ce the amount of
17ed0 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65 64  .** I/O required
17ee0 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61 74   to support stat
17ef0 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a  ement rollback..
17f00 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  ** The default v
17f10 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73 65  alue for this se
17f20 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f 6c  tting is control
17f30 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53  led by the.** [S
17f40 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53  QLITE_STMTJRNL_S
17f50 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  PILL] compile-ti
17f60 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  me option..**.**
17f70 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
17f80 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 5d  _SORTERREF_SIZE]
17f90 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
17fa0 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46  CONFIG_SORTERREF
17fb0 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 54 68 65  _SIZE.** <dd>The
17fc0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
17fd0 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 20 6f 70  ORTERREF_SIZE op
17fe0 74 69 6f 6e 20 61 63 63 65 70 74 73 20 61 20 73  tion accepts a s
17ff0 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 0a  ingle parameter.
18000 2a 2a 20 6f 66 20 74 79 70 65 20 28 69 6e 74 29  ** of type (int)
18010 20 2d 20 74 68 65 20 6e 65 77 20 76 61 6c 75 65   - the new value
18020 20 6f 66 20 74 68 65 20 73 6f 72 74 65 72 2d 72   of the sorter-r
18030 65 66 65 72 65 6e 63 65 20 73 69 7a 65 20 74 68  eference size th
18040 72 65 73 68 6f 6c 64 2e 0a 2a 2a 20 55 73 75 61  reshold..** Usua
18050 6c 6c 79 2c 20 77 68 65 6e 20 53 51 4c 69 74 65  lly, when SQLite
18060 20 75 73 65 73 20 61 6e 20 65 78 74 65 72 6e 61   uses an externa
18070 6c 20 73 6f 72 74 20 74 6f 20 6f 72 64 65 72 20  l sort to order 
18080 72 65 63 6f 72 64 73 20 61 63 63 6f 72 64 69 6e  records accordin
18090 67 0a 2a 2a 20 74 6f 20 61 6e 20 4f 52 44 45 52  g.** to an ORDER
180a0 20 42 59 20 63 6c 61 75 73 65 2c 20 61 6c 6c 20   BY clause, all 
180b0 66 69 65 6c 64 73 20 72 65 71 75 69 72 65 64 20  fields required 
180c0 62 79 20 74 68 65 20 63 61 6c 6c 65 72 20 61 72  by the caller ar
180d0 65 20 70 72 65 73 65 6e 74 20 69 6e 20 74 68 65  e present in the
180e0 0a 2a 2a 20 73 6f 72 74 65 64 20 72 65 63 6f 72  .** sorted recor
180f0 64 73 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20  ds. However, if 
18100 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
18110 73 20 62 61 73 65 64 20 6f 6e 20 74 68 65 20 64  s based on the d
18120 65 63 6c 61 72 65 64 20 74 79 70 65 0a 2a 2a 20  eclared type.** 
18130 6f 66 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  of a table colum
18140 6e 20 74 68 61 74 20 69 74 73 20 76 61 6c 75 65  n that its value
18150 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20  s are likely to 
18160 62 65 20 76 65 72 79 20 6c 61 72 67 65 20 2d 20  be very large - 
18170 6c 61 72 67 65 72 0a 2a 2a 20 74 68 61 6e 20 74  larger.** than t
18180 68 65 20 63 6f 6e 66 69 67 75 72 65 64 20 73 6f  he configured so
18190 72 74 65 72 2d 72 65 66 65 72 65 6e 63 65 20 73  rter-reference s
181a0 69 7a 65 20 74 68 72 65 73 68 6f 6c 64 20 2d 20  ize threshold - 
181b0 74 68 65 6e 20 61 20 72 65 66 65 72 65 6e 63 65  then a reference
181c0 0a 2a 2a 20 69 73 20 73 74 6f 72 65 64 20 69 6e  .** is stored in
181d0 20 65 61 63 68 20 73 6f 72 74 65 64 20 72 65 63   each sorted rec
181e0 6f 72 64 20 61 6e 64 20 74 68 65 20 72 65 71 75  ord and the requ
181f0 69 72 65 64 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ired column valu
18200 65 73 20 6c 6f 61 64 65 64 0a 2a 2a 20 66 72 6f  es loaded.** fro
18210 6d 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  m the database a
18220 73 20 72 65 63 6f 72 64 73 20 61 72 65 20 72 65  s records are re
18230 74 75 72 6e 65 64 20 69 6e 20 73 6f 72 74 65 64  turned in sorted
18240 20 6f 72 64 65 72 2e 20 54 68 65 20 64 65 66 61   order. The defa
18250 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 66 6f 72  ult.** value for
18260 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
18270 74 6f 20 6e 65 76 65 72 20 75 73 65 20 74 68 69  to never use thi
18280 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20  s optimization. 
18290 53 70 65 63 69 66 79 69 6e 67 20 61 20 0a 2a 2a  Specifying a .**
182a0 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
182b0 66 6f 72 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  for this option 
182c0 72 65 73 74 6f 72 65 73 20 74 68 65 20 64 65 66  restores the def
182d0 61 75 6c 74 20 62 65 68 61 76 69 6f 75 72 2e 0a  ault behaviour..
182e0 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  ** This option i
182f0 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
18300 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
18310 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
18320 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
18330 45 5f 53 4f 52 54 45 52 5f 52 45 46 45 52 45 4e  E_SORTER_REFEREN
18340 43 45 53 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  CES] compile-tim
18350 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64  e option..** </d
18360 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
18370 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
18380 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20  LETHREAD  1  /* 
18390 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
183a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
183b0 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a  TITHREAD   2  /*
183c0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
183d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
183e0 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f  RIALIZED    3  /
183f0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
18400 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
18410 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20  ALLOC        4  
18420 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
18430 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
18440 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18450 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35  _GETMALLOC     5
18460 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
18470 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
18480 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18490 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20  IG_SCRATCH      
184a0 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72   6  /* No longer
184b0 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
184c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
184d0 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
184e0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
184f0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
18500 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18510 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
18520 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
18530 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
18540 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18550 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
18560 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
18570 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
18580 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
18590 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
185a0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
185b0 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
185c0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
185d0 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
185e0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
185f0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f  ex_methods* */./
18600 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c  * previously SQL
18610 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b  ITE_CONFIG_CHUNK
18620 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69  ALLOC 12 which i
18630 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f  s now unused. */
18640 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45   .#define SQLITE
18650 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
18660 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
18670 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
18680 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
18690 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a  CHE       14  /*
186a0 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
186b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
186c0 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
186d0 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
186e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
186f0 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20  IG_LOG          
18700 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f  16  /* xFunc, vo
18710 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
18720 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
18730 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a            17  /*
18740 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
18750 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
18760 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f  ACHE2      18  /
18770 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
18780 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
18790 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
187a0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20  FIG_GETPCACHE2  
187b0 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   19  /* sqlite3_
187c0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
187d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
187e0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
187f0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30  NG_INDEX_SCAN 20
18800 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
18810 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18820 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32  G_SQLLOG       2
18830 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76  1  /* xSqllog, v
18840 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
18850 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
18860 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f  AP_SIZE    22  /
18870 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  * sqlite3_int64,
18880 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
18890 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
188a0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
188b0 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20  APSIZE      23  
188c0 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a  /* int nByte */.
188d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
188e0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
188f0 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a  SZ        24  /*
18900 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65   int *psz */.#de
18910 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18920 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20  IG_PMASZ        
18930 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e         25  /* un
18940 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61  signed int szPma
18950 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18960 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
18970 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32 36  NL_SPILL      26
18980 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
18990 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
189a0 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41  _CONFIG_SMALL_MA
189b0 4c 4c 4f 43 20 20 20 20 20 20 20 20 32 37 20 20  LLOC        27  
189c0 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64  /* boolean */.#d
189d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
189e0 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49  FIG_SORTERREF_SI
189f0 5a 45 20 20 20 20 20 20 32 38 20 20 2f 2a 20 69  ZE      28  /* i
18a00 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a  nt nByte */../*.
18a10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
18a20 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
18a30 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
18a40 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ptions.**.** The
18a50 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
18a60 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
18a70 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
18a80 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
18a90 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
18aa0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
18ab0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
18ac0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
18ad0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
18ae0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
18af0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
18b00 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
18b10 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
18b20 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
18b30 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
18b40 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
18b50 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
18b60 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
18b70 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
18b80 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
18b90 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
18ba0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74  3_db_config()] t
18bb0 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
18bc0 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
18bd0 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69  ked.  ^The [sqli
18be0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
18bf0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
18c00 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
18c10 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
18c20 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
18c30 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
18c40 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
18c50 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
18c60 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
18c70 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
18c80 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
18c90 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
18ca0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
18cb0 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f  es three additio
18cc0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68  nal arguments th
18cd0 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
18ce0 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20   .** [lookaside 
18cf0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
18d00 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
18d10 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73  for the [databas
18d20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
18d30 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
18d40 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
18d50 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
18d60 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
18d70 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
18d80 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
18d90 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f  buffer to use fo
18da0 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  r lookaside memo
18db0 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  ry..** ^The firs
18dc0 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72  t argument after
18dd0 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f   the SQLITE_DBCO
18de0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76  NFIG_LOOKASIDE v
18df0 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55  erb.** may be NU
18e00 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  LL in which case
18e10 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c   SQLite will all
18e20 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f  ocate the.** loo
18e30 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74  kaside buffer it
18e40 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69  self using [sqli
18e50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e  te3_malloc()]. ^
18e60 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
18e70 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
18e80 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
18e90 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
18ea0 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  .  ^The third ar
18eb0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75  gument is the nu
18ec0 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
18ed0 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
18ee0 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65  he buffer in the
18ef0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
18f00 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20  must be greater 
18f10 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c  than.** or equal
18f20 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20   to the product 
18f30 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  of the second an
18f40 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  d third argument
18f50 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a  s.  The buffer.*
18f60 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  * must be aligne
18f70 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
18f80 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68  oundary.  ^If th
18f90 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
18fa0 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44  t to.** SQLITE_D
18fb0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
18fc0 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69  E is not a multi
18fd0 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20  ple of 8, it is 
18fe0 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f  internally.** ro
18ff0 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68  unded down to th
19000 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d  e next smaller m
19010 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e  ultiple of 8.  ^
19020 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  (The lookaside m
19030 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75  emory.** configu
19040 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74  ration for a dat
19050 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19060 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61   can only be cha
19070 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a  nged when that.*
19080 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
19090 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73  not currently us
190a0 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ing lookaside me
190b0 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65  mory, or in othe
190c0 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20  r words.** when 
190d0 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c  the "current val
190e0 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ue" returned by.
190f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73  ** [sqlite3_db_s
19100 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45  tatus](D,[SQLITE
19110 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
19120 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e  E],...) is zero.
19130 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
19140 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f  to change the lo
19150 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63  okaside memory c
19160 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65  onfiguration whe
19170 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d  n lookaside.** m
19180 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20  emory is in use 
19190 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69  leaves the confi
191a0 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67  guration unchang
191b0 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a  ed and returns .
191c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
191d0 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  .)^</dd>.**.** <
191e0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
191f0 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f  IG_ENABLE_FKEY</
19200 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
19210 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
19220 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
19230 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63  sable the enforc
19240 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72  ement of.** [for
19250 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61  eign key constra
19260 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68  ints].  There sh
19270 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
19280 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
19290 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
192a0 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
192b0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
192c0 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65   to disable FK e
192d0 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70  nforcement,.** p
192e0 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
192f0 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
19300 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
19310 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65  leave FK enforce
19320 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65  ment.** unchange
19330 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  d.  The second p
19340 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
19350 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
19360 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
19370 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
19380 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
19390 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72  whether FK enfor
193a0 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72  cement is off or
193b0 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67   on.** following
193c0 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
193d0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
193e0 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
193f0 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
19400 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b  hich case the FK
19410 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74   enforcement set
19420 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
19430 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
19440 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
19450 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
19460 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a  E_TRIGGER</dt>.*
19470 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
19480 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
19490 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
194a0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
194b0 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a   | triggers]..**
194c0 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
194d0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
194e0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
194f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
19500 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
19510 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
19520 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a  able triggers,.*
19530 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
19540 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72  able triggers or
19550 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
19560 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75  ve the setting u
19570 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
19580 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
19590 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
195a0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
195b0 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
195c0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
195d0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
195e0 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69   triggers are di
195f0 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65  sabled or enable
19600 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  d.** following t
19610 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
19620 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
19630 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
19640 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
19650 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67  ch case the trig
19660 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ger setting is n
19670 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
19680 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
19690 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
196a0 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f  G_ENABLE_FTS3_TO
196b0 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20  KENIZER</dt>.** 
196c0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
196d0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
196e0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
196f0 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a  he two-argument.
19700 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ** version of th
19710 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65  e [fts3_tokenize
19720 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68  r()] function wh
19730 69 63 68 20 69 73 20 70 61 72 74 20 6f 66 20 74  ich is part of t
19740 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c  he.** [FTS3] ful
19750 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20 65 6e  l-text search en
19760 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a  gine extension..
19770 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
19780 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
19790 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
197a0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
197b0 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
197c0 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
197d0 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65  isable fts3_toke
197e0 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f  nizer() or.** po
197f0 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
19800 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28   fts3_tokenizer(
19810 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  ) or negative to
19820 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
19830 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  ng.** unchanged.
19840 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
19850 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
19860 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
19870 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
19880 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
19890 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
198a0 77 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b  whether fts3_tok
198b0 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  enizer is disabl
198c0 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a  ed or enabled.**
198d0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
198e0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
198f0 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
19900 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
19910 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
19920 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74  ase the new sett
19930 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
19940 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
19950 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
19960 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
19970 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c  _LOAD_EXTENSION<
19980 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
19990 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
199a0 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
199b0 69 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69  isable the [sqli
199c0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
199d0 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  on()].** interfa
199e0 63 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79  ce independently
199f0 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78   of the [load_ex
19a00 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66  tension()] SQL f
19a10 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20  unction..** The 
19a20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
19a30 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
19a40 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72  ] API enables or
19a50 20 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74   disables both t
19a60 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c  he.** C-API [sql
19a70 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
19a80 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53  ion()] and the S
19a90 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61  QL function [loa
19aa0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a  d_extension()]..
19ab0 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
19ac0 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
19ad0 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
19ae0 57 68 65 6e 20 74 68 65 20 66 69 72 73 74 20 61  When the first a
19af0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
19b00 69 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c 20  interface is 1, 
19b10 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d  then only the C-
19b20 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65  API is.** enable
19b30 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75  d and the SQL fu
19b40 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64  nction remains d
19b50 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65  isabled.  If the
19b60 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
19b70 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72  to.** this inter
19b80 66 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20  face is 0, then 
19b90 62 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20 61  both the C-API a
19ba0 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nd the SQL funct
19bb0 69 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64  ion are disabled
19bc0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73  ..** If the firs
19bd0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31  t argument is -1
19be0 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65  , then no change
19bf0 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74  s are made to st
19c00 61 74 65 20 6f 66 20 65 69 74 68 65 72 20 74 68  ate of either th
19c10 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68  e.** C-API or th
19c20 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a  e SQL function..
19c30 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
19c40 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
19c50 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
19c60 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
19c70 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
19c80 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
19c90 68 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  hether [sqlite3_
19ca0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
19cb0 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  ] interface.** i
19cc0 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  s disabled or en
19cd0 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20  abled following 
19ce0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
19cf0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
19d00 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c   may.** be a NUL
19d10 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68  L pointer, in wh
19d20 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77  ich case the new
19d30 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
19d40 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a  reported back..*
19d50 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
19d60 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
19d70 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74  G_MAINDBNAME</dt
19d80 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
19d90 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
19da0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61 6d  o change the nam
19db0 65 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22 20  e of the "main" 
19dc0 64 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68 65  database.** sche
19dd0 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20 61  ma.  ^The sole a
19de0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
19df0 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74 61  nter to a consta
19e00 6e 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a  nt UTF8 string.*
19e10 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 63  * which will bec
19e20 6f 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68 65  ome the new sche
19e30 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65  ma name in place
19e40 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51   of "main".  ^SQ
19e50 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  Lite.** does not
19e60 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20   make a copy of 
19e70 74 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63 68  the new main sch
19e80 65 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c  ema name string,
19e90 20 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   so the applicat
19ea0 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75  ion.** must ensu
19eb0 72 65 20 74 68 61 74 20 74 68 65 20 61 72 67 75  re that the argu
19ec0 6d 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74 6f  ment passed into
19ed0 20 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20 6f   this DBCONFIG o
19ee0 70 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67  ption is unchang
19ef0 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65  ed.** until afte
19f00 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  r the database c
19f10 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
19f20 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
19f30 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
19f40 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f  NFIG_NO_CKPT_ON_
19f50 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CLOSE</dt>.** <d
19f60 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e  d> Usually, when
19f70 20 61 20 64 61 74 61 62 61 73 65 20 69 6e 20 77   a database in w
19f80 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73 65  al mode is close
19f90 64 20 6f 72 20 64 65 74 61 63 68 65 64 20 66 72  d or detached fr
19fa0 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62 61 73  om a .** databas
19fb0 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74 65  e handle, SQLite
19fc0 20 63 68 65 63 6b 73 20 69 66 20 74 68 69 73 20   checks if this 
19fd0 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20 74  will mean that t
19fe0 68 65 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f 20  here are now no 
19ff0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  .** connections 
1a000 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 20 64 61  at all to the da
1a010 74 61 62 61 73 65 2e 20 49 66 20 73 6f 2c 20 69  tabase. If so, i
1a020 74 20 70 65 72 66 6f 72 6d 73 20 61 20 63 68 65  t performs a che
1a030 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65 72  ckpoint .** oper
1a040 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c 6f  ation before clo
1a050 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74  sing the connect
1a060 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f 6e  ion. This option
1a070 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 0a   may be used to.
1a080 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 68 69 73  ** override this
1a090 20 62 65 68 61 76 69 6f 75 72 2e 20 54 68 65 20   behaviour. The 
1a0a0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1a0b0 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f  passed to this o
1a0c0 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 61  peration.** is a
1a0d0 6e 20 69 6e 74 65 67 65 72 20 2d 20 70 6f 73 69  n integer - posi
1a0e0 74 69 76 65 20 74 6f 20 64 69 73 61 62 6c 65 20  tive to disable 
1a0f0 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63  checkpoints-on-c
1a100 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28 74  lose, or zero (t
1a110 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20 74  he.** default) t
1a120 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d 2c 20 61  o enable them, a
1a130 6e 64 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  nd negative to l
1a140 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
1a150 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54   unchanged..** T
1a160 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1a170 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
1a180 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   to an integer.*
1a190 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73 20  * into which is 
1a1a0 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
1a1b0 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
1a1c0 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f  er checkpoints-o
1a1d0 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65 20  n-close.** have 
1a1e0 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d 20  been disabled - 
1a1f0 30 20 69 66 20 74 68 65 79 20 61 72 65 20 6e 6f  0 if they are no
1a200 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69 66  t disabled, 1 if
1a210 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c 2f   they are..** </
1a220 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
1a230 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
1a240 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74 3e 0a 2a  ABLE_QPSG</dt>.*
1a250 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49  * <dd>^(The SQLI
1a260 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
1a270 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f 6e 20 61  LE_QPSG option a
1a280 63 74 69 76 61 74 65 73 20 6f 72 20 64 65 61 63  ctivates or deac
1a290 74 69 76 61 74 65 73 0a 2a 2a 20 74 68 65 20 5b  tivates.** the [
1a2a0 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 73 74  query planner st
1a2b0 61 62 69 6c 69 74 79 20 67 75 61 72 61 6e 74 65  ability guarante
1a2c0 65 5d 20 28 51 50 53 47 29 2e 20 20 57 68 65 6e  e] (QPSG).  When
1a2d0 20 74 68 65 20 51 50 53 47 20 69 73 20 61 63 74   the QPSG is act
1a2e0 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e 67 6c 65  ive,.** a single
1a2f0 20 53 51 4c 20 71 75 65 72 79 20 73 74 61 74 65   SQL query state
1a300 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77 61 79 73  ment will always
1a310 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 61 6c   use the same al
1a320 67 6f 72 69 74 68 6d 20 72 65 67 61 72 64 6c 65  gorithm regardle
1a330 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75 65 73 20  ss.** of values 
1a340 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  of [bound parame
1a350 74 65 72 73 5d 2e 29 5e 20 54 68 65 20 51 50 53  ters].)^ The QPS
1a360 47 20 64 69 73 61 62 6c 65 73 20 73 6f 6d 65 20  G disables some 
1a370 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 61 74 69  query optimizati
1a380 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c 6f 6f 6b  ons.** that look
1a390 20 61 74 20 74 68 65 20 76 61 6c 75 65 73 20 6f   at the values o
1a3a0 66 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  f bound paramete
1a3b0 72 73 2c 20 77 68 69 63 68 20 63 61 6e 20 6d 61  rs, which can ma
1a3c0 6b 65 20 73 6f 6d 65 20 71 75 65 72 69 65 73 0a  ke some queries.
1a3d0 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42 75 74 20  ** slower.  But 
1a3e0 74 68 65 20 51 50 53 47 20 68 61 73 20 74 68 65  the QPSG has the
1a3f0 20 61 64 76 61 6e 74 61 67 65 20 6f 66 20 6d 6f   advantage of mo
1a400 72 65 20 70 72 65 64 69 63 74 61 62 6c 65 20 62  re predictable b
1a410 65 68 61 76 69 6f 72 2e 20 20 57 69 74 68 0a 2a  ehavior.  With.*
1a420 2a 20 74 68 65 20 51 50 53 47 20 61 63 74 69 76  * the QPSG activ
1a430 65 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  e, SQLite will a
1a440 6c 77 61 79 73 20 75 73 65 20 74 68 65 20 73 61  lways use the sa
1a450 6d 65 20 71 75 65 72 79 20 70 6c 61 6e 20 69 6e  me query plan in
1a460 20 74 68 65 20 66 69 65 6c 64 20 61 73 0a 2a 2a   the field as.**
1a470 20 77 61 73 20 75 73 65 64 20 64 75 72 69 6e 67   was used during
1a480 20 74 65 73 74 69 6e 67 20 69 6e 20 74 68 65 20   testing in the 
1a490 6c 61 62 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  lab..** The firs
1a4a0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
1a4b0 69 73 20 73 65 74 74 69 6e 67 20 69 73 20 61 6e  is setting is an
1a4c0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
1a4d0 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 0a  s 0 to disable .
1a4e0 2a 2a 20 74 68 65 20 51 50 53 47 2c 20 70 6f 73  ** the QPSG, pos
1a4f0 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
1a500 51 50 53 47 2c 20 6f 72 20 6e 65 67 61 74 69 76  QPSG, or negativ
1a510 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
1a520 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e  etting.** unchan
1a530 67 65 64 2e 20 54 68 65 20 73 65 63 6f 6e 64 20  ged. The second 
1a540 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
1a550 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
1a560 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
1a570 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
1a580 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
1a590 20 77 68 65 74 68 65 72 20 74 68 65 20 51 50 53   whether the QPS
1a5a0 47 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72  G is disabled or
1a5b0 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
1a5c0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
1a5d0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
1a5e0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
1a5f0 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50 3c  FIG_TRIGGER_EQP<
1a600 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 42 79 20  /dt>.** <dd> By 
1a610 64 65 66 61 75 6c 74 2c 20 74 68 65 20 6f 75 74  default, the out
1a620 70 75 74 20 6f 66 20 45 58 50 4c 41 49 4e 20 51  put of EXPLAIN Q
1a630 55 45 52 59 20 50 4c 41 4e 20 63 6f 6d 6d 61 6e  UERY PLAN comman
1a640 64 73 20 64 6f 65 73 20 6e 6f 74 20 0a 2a 2a 20  ds does not .** 
1a650 69 6e 63 6c 75 64 65 20 6f 75 74 70 75 74 20 66  include output f
1a660 6f 72 20 61 6e 79 20 6f 70 65 72 61 74 69 6f 6e  or any operation
1a670 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  s performed by t
1a680 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e  rigger programs.
1a690 20 54 68 69 73 0a 2a 2a 20 6f 70 74 69 6f 6e 20   This.** option 
1a6a0 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
1a6b0 72 20 63 6c 65 61 72 20 28 74 68 65 20 64 65 66  r clear (the def
1a6c0 61 75 6c 74 29 20 61 20 66 6c 61 67 20 74 68 61  ault) a flag tha
1a6d0 74 20 67 6f 76 65 72 6e 73 20 74 68 69 73 0a 2a  t governs this.*
1a6e0 2a 20 62 65 68 61 76 69 6f 72 2e 20 54 68 65 20  * behavior. The 
1a6f0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1a700 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f  passed to this o
1a710 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 69  peration is an i
1a720 6e 74 65 67 65 72 20 2d 0a 2a 2a 20 70 6f 73 69  nteger -.** posi
1a730 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 6f  tive to enable o
1a740 75 74 70 75 74 20 66 6f 72 20 74 72 69 67 67 65  utput for trigge
1a750 72 20 70 72 6f 67 72 61 6d 73 2c 20 6f 72 20 7a  r programs, or z
1a760 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20 69  ero to disable i
1a770 74 2c 0a 2a 2a 20 6f 72 20 6e 65 67 61 74 69 76  t,.** or negativ
1a780 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
1a790 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
1a7a0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
1a7b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
1a7c0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
1a7d0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 20  eger into which 
1a7e0 69 73 20 77 72 69 74 74 65 6e 20 0a 2a 2a 20 30  is written .** 0
1a7f0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
1a800 65 20 77 68 65 74 68 65 72 20 6f 75 74 70 75 74  e whether output
1a810 2d 66 6f 72 2d 74 72 69 67 67 65 72 73 20 68 61  -for-triggers ha
1a820 73 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20  s been disabled 
1a830 2d 20 30 20 69 66 20 0a 2a 2a 20 69 74 20 69 73  - 0 if .** it is
1a840 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31   not disabled, 1
1a850 20 69 66 20 69 74 20 69 73 2e 20 20 0a 2a 2a 20   if it is.  .** 
1a860 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1a870 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1a880 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 3c 2f  RESET_DATABASE</
1a890 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 53 65 74 20  dt>.** <dd> Set 
1a8a0 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
1a8b0 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41  FIG_RESET_DATABA
1a8c0 53 45 20 66 6c 61 67 20 61 6e 64 20 74 68 65 6e  SE flag and then
1a8d0 20 72 75 6e 0a 2a 2a 20 5b 56 41 43 55 55 4d 5d   run.** [VACUUM]
1a8e0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 73   in order to res
1a8f0 65 74 20 61 20 64 61 74 61 62 61 73 65 20 62 61  et a database ba
1a900 63 6b 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 64  ck to an empty d
1a910 61 74 61 62 61 73 65 0a 2a 2a 20 77 69 74 68 20  atabase.** with 
1a920 6e 6f 20 73 63 68 65 6d 61 20 61 6e 64 20 6e 6f  no schema and no
1a930 20 63 6f 6e 74 65 6e 74 2e 20 54 68 65 20 66 6f   content. The fo
1a940 6c 6c 6f 77 69 6e 67 20 70 72 6f 63 65 73 73 20  llowing process 
1a950 77 6f 72 6b 73 20 65 76 65 6e 20 66 6f 72 0a 2a  works even for.*
1a960 2a 20 61 20 62 61 64 6c 79 20 63 6f 72 72 75 70  * a badly corrup
1a970 74 65 64 20 64 61 74 61 62 61 73 65 20 66 69 6c  ted database fil
1a980 65 3a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  e:.** <ol>.** <l
1a990 69 3e 20 49 66 20 74 68 65 20 64 61 74 61 62 61  i> If the databa
1a9a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1a9b0 20 6e 65 77 6c 79 20 6f 70 65 6e 65 64 2c 20 6d   newly opened, m
1a9c0 61 6b 65 20 73 75 72 65 20 69 74 20 68 61 73 20  ake sure it has 
1a9d0 72 65 61 64 20 74 68 65 0a 2a 2a 20 20 20 20 20  read the.**     
1a9e0 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
1a9f0 20 62 79 20 70 72 65 70 61 72 69 6e 67 20 74 68   by preparing th
1aa00 65 6e 20 64 69 73 63 61 72 64 69 6e 67 20 73 6f  en discarding so
1aa10 6d 65 20 71 75 65 72 79 20 61 67 61 69 6e 73 74  me query against
1aa20 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 64 61 74   the.**      dat
1aa30 61 62 61 73 65 2c 20 6f 72 20 63 61 6c 6c 69 6e  abase, or callin
1aa40 67 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f  g sqlite3_table_
1aa50 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28  column_metadata(
1aa60 29 2c 20 69 67 6e 6f 72 69 6e 67 20 61 6e 79 0a  ), ignoring any.
1aa70 2a 2a 20 20 20 20 20 20 65 72 72 6f 72 73 2e 20  **      errors. 
1aa80 20 54 68 69 73 20 73 74 65 70 20 69 73 20 6f 6e   This step is on
1aa90 6c 79 20 6e 65 63 65 73 73 61 72 79 20 69 66 20  ly necessary if 
1aaa0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1aab0 64 65 73 69 72 65 73 20 74 6f 20 6b 65 65 70 0a  desires to keep.
1aac0 2a 2a 20 20 20 20 20 20 74 68 65 20 64 61 74 61  **      the data
1aad0 62 61 73 65 20 69 6e 20 57 41 4c 20 6d 6f 64 65  base in WAL mode
1aae0 20 61 66 74 65 72 20 74 68 65 20 72 65 73 65 74   after the reset
1aaf0 20 69 66 20 69 74 20 77 61 73 20 69 6e 20 57 41   if it was in WA
1ab00 4c 20 6d 6f 64 65 20 62 65 66 6f 72 65 0a 2a 2a  L mode before.**
1ab10 20 20 20 20 20 20 74 68 65 20 72 65 73 65 74 2e        the reset.
1ab20 20 20 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74    .** <li> sqlit
1ab30 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 64 62 2c  e3_db_config(db,
1ab40 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1ab50 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 2c  _RESET_DATABASE,
1ab60 20 31 2c 20 30 29 3b 0a 2a 2a 20 3c 6c 69 3e 20   1, 0);.** <li> 
1ab70 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 5d 28 64  [sqlite3_exec](d
1ab80 62 2c 20 22 5b 56 41 43 55 55 4d 5d 22 2c 20 30  b, "[VACUUM]", 0
1ab90 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 3c 6c 69 3e  , 0, 0);.** <li>
1aba0 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
1abb0 69 67 28 64 62 2c 20 53 51 4c 49 54 45 5f 44 42  ig(db, SQLITE_DB
1abc0 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54  CONFIG_RESET_DAT
1abd0 41 42 41 53 45 2c 20 30 2c 20 30 29 3b 0a 2a 2a  ABASE, 0, 0);.**
1abe0 20 3c 2f 6f 6c 3e 0a 2a 2a 20 42 65 63 61 75 73   </ol>.** Becaus
1abf0 65 20 72 65 73 65 74 74 69 6e 67 20 61 20 64 61  e resetting a da
1ac00 74 61 62 61 73 65 20 69 73 20 64 65 73 74 72 75  tabase is destru
1ac10 63 74 69 76 65 20 61 6e 64 20 69 72 72 65 76 65  ctive and irreve
1ac20 72 73 69 62 6c 65 2c 20 74 68 65 0a 2a 2a 20 70  rsible, the.** p
1ac30 72 6f 63 65 73 73 20 72 65 71 75 69 72 65 73 20  rocess requires 
1ac40 74 68 65 20 75 73 65 20 6f 66 20 74 68 69 73 20  the use of this 
1ac50 6f 62 73 63 75 72 65 20 41 50 49 20 61 6e 64 20  obscure API and 
1ac60 6d 75 6c 74 69 70 6c 65 20 73 74 65 70 73 20 74  multiple steps t
1ac70 6f 20 68 65 6c 70 0a 2a 2a 20 65 6e 73 75 72 65  o help.** ensure
1ac80 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f   that it does no
1ac90 74 20 68 61 70 70 65 6e 20 62 79 20 61 63 63 69  t happen by acci
1aca0 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  dent..**.** <dt>
1acb0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1acc0 44 45 46 45 4e 53 49 56 45 3c 2f 64 74 3e 0a 2a  DEFENSIVE</dt>.*
1acd0 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45  * <dd>The SQLITE
1ace0 5f 44 42 43 4f 4e 46 49 47 5f 44 45 46 45 4e 53  _DBCONFIG_DEFENS
1acf0 49 56 45 20 6f 70 74 69 6f 6e 20 61 63 74 69 76  IVE option activ
1ad00 65 73 20 6f 72 20 64 65 61 63 74 69 76 61 74 65  es or deactivate
1ad10 73 20 74 68 65 0a 2a 2a 20 22 64 65 66 65 6e 73  s the.** "defens
1ad20 69 76 65 22 20 66 6c 61 67 20 66 6f 72 20 61 20  ive" flag for a 
1ad30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ad40 69 6f 6e 2e 20 20 57 68 65 6e 20 74 68 65 20 64  ion.  When the d
1ad50 65 66 65 6e 73 69 76 65 0a 2a 2a 20 66 6c 61 67  efensive.** flag
1ad60 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 73 6f 6d   is enabled, som
1ad70 65 20 6f 62 73 63 75 72 65 20 66 65 61 74 75 72  e obscure featur
1ad80 65 73 20 6f 66 20 53 51 4c 69 74 65 20 61 72 65  es of SQLite are
1ad90 20 64 69 73 61 62 6c 65 64 20 69 6e 20 6f 72 64   disabled in ord
1ada0 65 72 0a 2a 2a 20 74 6f 20 72 65 64 75 63 65 20  er.** to reduce 
1adb0 74 68 65 20 61 74 74 61 63 6b 20 73 75 72 66 61  the attack surfa
1adc0 63 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  ce. Applications
1add0 20 74 68 61 74 20 72 75 6e 20 75 6e 74 72 75 73   that run untrus
1ade0 74 65 64 20 53 51 4c 0a 2a 2a 20 63 61 6e 20 61  ted SQL.** can a
1adf0 63 74 69 76 61 74 65 20 74 68 69 73 20 66 6c 61  ctivate this fla
1ae00 67 20 74 6f 20 72 65 64 75 63 65 20 74 68 65 20  g to reduce the 
1ae10 72 69 73 6b 20 6f 66 20 7a 65 72 6f 2d 64 61 79  risk of zero-day
1ae20 20 65 78 70 6c 6f 69 74 73 2e 0a 2a 2a 20 3c 70   exploits..** <p
1ae30 3e 0a 2a 2a 20 46 65 61 74 75 72 65 73 20 64 69  >.** Features di
1ae40 73 61 62 6c 65 64 20 62 79 20 74 68 65 20 64 65  sabled by the de
1ae50 66 65 6e 73 69 76 65 20 66 6c 61 67 20 69 6e 63  fensive flag inc
1ae60 6c 75 64 65 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  lude:.** <ul>.**
1ae70 20 3c 6c 69 3e 54 68 65 20 5b 50 52 41 47 4d 41   <li>The [PRAGMA
1ae80 20 77 72 69 74 61 62 6c 65 5f 73 63 68 65 6d 61   writable_schema
1ae90 3d 4f 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  =ON] statement..
1aea0 2a 2a 20 3c 6c 69 3e 57 72 69 74 65 73 20 74 6f  ** <li>Writes to
1aeb0 20 74 68 65 20 5b 73 71 6c 69 74 65 5f 64 62 70   the [sqlite_dbp
1aec0 61 67 65 5d 20 76 69 72 74 75 61 6c 20 74 61 62  age] virtual tab
1aed0 6c 65 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  le..** </ul>.** 
1aee0 4e 65 77 20 72 65 73 74 72 69 63 74 69 6f 6e 73  New restrictions
1aef0 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
1af00 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
1af10 2e 0a 2a 2a 20 3c 70 3e 0a 2a 2a 20 54 6f 20 62  ..** <p>.** To b
1af20 65 20 63 6c 65 61 72 3a 20 49 74 20 73 68 6f 75  e clear: It shou
1af30 6c 64 20 6e 65 76 65 72 20 62 65 20 70 6f 73 73  ld never be poss
1af40 69 62 6c 65 20 66 6f 72 20 68 6f 73 74 69 6c 65  ible for hostile
1af50 20 53 51 4c 20 74 6f 20 63 61 75 73 65 0a 2a 2a   SQL to cause.**
1af60 20 61 72 62 69 74 72 61 72 79 20 6d 65 6d 6f 72   arbitrary memor
1af70 79 20 72 65 61 64 73 2c 20 6d 65 6d 6f 72 79 20  y reads, memory 
1af80 6c 65 61 6b 73 2c 20 62 75 66 66 65 72 20 6f 76  leaks, buffer ov
1af90 65 72 66 6c 6f 77 73 2c 20 61 73 73 65 72 74 69  erflows, asserti
1afa0 6f 6e 0a 2a 2a 20 66 61 75 6c 74 73 2c 20 61 72  on.** faults, ar
1afb0 62 69 74 72 61 72 79 20 63 6f 64 65 20 65 78 65  bitrary code exe
1afc0 63 75 74 69 6f 6e 2c 20 63 72 61 73 68 65 73 2c  cution, crashes,
1afd0 20 6f 72 20 6f 74 68 65 72 20 6d 69 73 63 68 69   or other mischi
1afe0 65 66 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a  ef, regardless.*
1aff0 2a 20 6f 66 20 74 68 65 20 76 61 6c 75 65 20 6f  * of the value o
1b000 66 20 74 68 65 20 64 65 66 65 6e 73 69 76 65 20  f the defensive 
1b010 66 6c 61 67 2e 20 20 41 6e 79 20 6f 63 63 75 72  flag.  Any occur
1b020 72 61 6e 63 65 20 6f 66 20 74 68 65 73 65 20 70  rance of these p
1b030 72 6f 62 6c 65 6d 73 0a 2a 2a 20 69 73 20 63 6f  roblems.** is co
1b040 6e 73 69 64 65 72 65 64 20 61 20 73 65 72 69 6f  nsidered a serio
1b050 75 73 20 62 75 67 20 61 6e 64 20 77 69 6c 6c 20  us bug and will 
1b060 62 65 20 66 69 78 65 64 20 70 72 6f 6d 70 74 6c  be fixed promptl
1b070 79 2e 20 20 49 74 20 69 73 20 6e 6f 74 0a 2a 2a  y.  It is not.**
1b080 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 65 6e   necessary to en
1b090 61 62 6c 65 20 74 68 65 20 64 65 66 65 6e 73 69  able the defensi
1b0a0 76 65 20 66 6c 61 67 20 69 6e 20 6f 72 64 65 72  ve flag in order
1b0b0 20 74 6f 20 6d 61 6b 65 20 53 51 4c 69 74 65 20   to make SQLite 
1b0c0 73 65 63 75 72 65 0a 2a 2a 20 61 67 61 69 6e 73  secure.** agains
1b0d0 74 20 61 74 74 61 63 6b 2e 20 54 68 65 20 64 65  t attack. The de
1b0e0 66 65 6e 73 69 76 65 20 66 6c 61 67 20 6d 65 72  fensive flag mer
1b0f0 65 6c 79 20 70 72 6f 76 69 64 65 73 20 61 6e 20  ely provides an 
1b100 61 64 64 69 74 69 6f 6e 61 6c 20 6c 61 79 65 72  additional layer
1b110 0a 2a 2a 20 6f 66 20 64 65 66 65 6e 73 65 20 61  .** of defense a
1b120 67 61 69 6e 73 74 20 75 6e 6b 6e 6f 77 6e 20 76  gainst unknown v
1b130 75 6c 6e 65 72 61 62 69 6c 69 74 69 65 73 2e 0a  ulnerabilities..
1b140 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c  ** </dd>.** </dl
1b150 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
1b160 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49  ITE_DBCONFIG_MAI
1b170 4e 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20  NDBNAME         
1b180 20 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74     1000 /* const
1b190 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e   char* */.#defin
1b1a0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1b1b0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20  G_LOOKASIDE     
1b1c0 20 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20          1001 /* 
1b1d0 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
1b1e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b1f0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
1b200 46 4b 45 59 20 20 20 20 20 20 20 20 20 20 20 31  FKEY           1
1b210 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  002 /* int int* 
1b220 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b230 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
1b240 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
1b250 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74   1003 /* int int
1b260 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
1b270 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
1b280 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a  BLE_FTS3_TOKENIZ
1b290 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69  ER 1004 /* int i
1b2a0 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
1b2b0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
1b2c0 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e  NABLE_LOAD_EXTEN
1b2d0 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74  SION 1005 /* int
1b2e0 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
1b2f0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1b300 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53  _NO_CKPT_ON_CLOS
1b310 45 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20 69  E      1006 /* i
1b320 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
1b330 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
1b340 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 20  IG_ENABLE_QPSG  
1b350 20 20 20 20 20 20 20 20 20 31 30 30 37 20 2f 2a           1007 /*
1b360 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
1b370 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
1b380 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50  NFIG_TRIGGER_EQP
1b390 20 20 20 20 20 20 20 20 20 20 20 31 30 30 38 20             1008 
1b3a0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
1b3b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
1b3c0 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54  CONFIG_RESET_DAT
1b3d0 41 42 41 53 45 20 20 20 20 20 20 20 20 31 30 30  ABASE        100
1b3e0 39 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  9 /* int int* */
1b3f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b400 44 42 43 4f 4e 46 49 47 5f 44 45 46 45 4e 53 49  DBCONFIG_DEFENSI
1b410 56 45 20 20 20 20 20 20 20 20 20 20 20 20 20 31  VE             1
1b420 30 31 30 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  010 /* int int* 
1b430 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b440 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 58 20 20  E_DBCONFIG_MAX  
1b450 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1b460 20 31 30 31 30 20 2f 2a 20 4c 61 72 67 65 73 74   1010 /* Largest
1b470 20 44 42 43 4f 4e 46 49 47 20 2a 2f 0a 0a 2f 2a   DBCONFIG */../*
1b480 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
1b490 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
1b4a0 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
1b4b0 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Codes.** METHOD:
1b4c0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1b4d0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
1b4e0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
1b4f0 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
1b500 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
1b510 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
1b520 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
1b530 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
1b540 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
1b550 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
1b560 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
1b570 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
1b580 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
1b590 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
1b5a0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
1b5b0 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
1b5c0 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
1b5d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b5e0 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
1b5f0 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  wid.** METHOD: s
1b600 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61  qlite3.**.** ^Ea
1b610 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
1b620 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
1b630 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
1b640 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
1b650 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
1b660 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
1b670 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
1b680 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
1b690 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
1b6a0 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
1b6b0 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
1b6c0 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
1b6d0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
1b6e0 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
1b6f0 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
1b700 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
1b710 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
1b720 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
1b730 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
1b740 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
1b750 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
1b760 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
1b770 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
1b780 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
1b790 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
1b7a0 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
1b7b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1b7c0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1b7d0 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
1b7e0 63 65 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72  ce usually retur
1b7f0 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
1b800 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  f.** the most re
1b810 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20  cent successful 
1b820 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20  [INSERT] into a 
1b830 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b  rowid table or [
1b840 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
1b850 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f  * on database co
1b860 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73  nnection D. ^Ins
1b870 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f  erts into [WITHO
1b880 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
1b890 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f   are not.** reco
1b8a0 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63  rded. ^If no suc
1b8b0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
1b8c0 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62  s into rowid tab
1b8d0 6c 65 73 20 68 61 76 65 20 65 76 65 72 20 6f 63  les have ever oc
1b8e0 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68  curred .** on th
1b8f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1b900 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71  ction D, then sq
1b910 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
1b920 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72  t_rowid(D) retur
1b930 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a  ns .** zero..**.
1b940 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73 20 62 65  ** As well as be
1b950 69 6e 67 20 73 65 74 20 61 75 74 6f 6d 61 74 69  ing set automati
1b960 63 61 6c 6c 79 20 61 73 20 72 6f 77 73 20 61 72  cally as rows ar
1b970 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20  e inserted into 
1b980 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c  database.** tabl
1b990 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  es, the value re
1b9a0 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66  turned by this f
1b9b0 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 73  unction may be s
1b9c0 65 74 20 65 78 70 6c 69 63 69 74 6c 79 20 62 79  et explicitly by
1b9d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
1b9e0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1b9f0 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65  id()].**.** Some
1ba00 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
1ba10 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
1ba20 61 79 20 49 4e 53 45 52 54 20 72 6f 77 73 20 69  ay INSERT rows i
1ba30 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73  nto rowid tables
1ba40 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63   as.** part of c
1ba50 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74 72 61 6e  ommitting a tran
1ba60 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f  saction (e.g. to
1ba70 20 66 6c 75 73 68 20 64 61 74 61 20 61 63 63 75   flush data accu
1ba80 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72  mulated in memor
1ba90 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49  y.** to disk). I
1baa0 6e 20 74 68 69 73 20 63 61 73 65 20 73 75 62 73  n this case subs
1bab0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
1bac0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
1bad0 74 75 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a  turn the rowid.*
1bae0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
1baf0 68 20 74 68 65 73 65 20 69 6e 74 65 72 6e 61 6c  h these internal
1bb00 20 49 4e 53 45 52 54 20 6f 70 65 72 61 74 69 6f   INSERT operatio
1bb10 6e 73 2c 20 77 68 69 63 68 20 6c 65 61 64 73 20  ns, which leads 
1bb20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69  to .** unintuiti
1bb30 76 65 20 72 65 73 75 6c 74 73 2e 20 56 69 72 74  ve results. Virt
1bb40 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
1bb50 65 6e 74 61 74 69 6f 6e 73 20 74 68 61 74 20 64  entations that d
1bb60 6f 20 77 72 69 74 65 20 74 6f 20 72 6f 77 69 64  o write to rowid
1bb70 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e 20 74 68  .** tables in th
1bb80 69 73 20 77 61 79 20 63 61 6e 20 61 76 6f 69 64  is way can avoid
1bb90 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 62 79   this problem by
1bba0 20 72 65 73 74 6f 72 69 6e 67 20 74 68 65 20 6f   restoring the o
1bbb0 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69  riginal .** rowi
1bbc0 64 20 76 61 6c 75 65 20 75 73 69 6e 67 20 5b 73  d value using [s
1bbd0 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f  qlite3_set_last_
1bbe0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
1bbf0 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
1bc00 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20   .** control to 
1bc10 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20  the user..**.** 
1bc20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
1bc30 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
1bc40 20 74 72 69 67 67 65 72 20 74 68 65 6e 20 74 68   trigger then th
1bc50 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
1bc60 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 5b  .** return the [
1bc70 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
1bc80 73 65 72 74 65 64 20 72 6f 77 20 61 73 20 6c 6f  serted row as lo
1bc90 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
1bca0 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67  r is .** running
1bcb0 2e 20 4f 6e 63 65 20 74 68 65 20 74 72 69 67 67  . Once the trigg
1bcc0 65 72 20 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c  er program ends,
1bcd0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1bce0 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20  ned .** by this 
1bcf0 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
1bd00 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62  to what it was b
1bd10 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
1bd20 72 20 77 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a  r was fired.)^.*
1bd30 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
1bd40 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
1bd50 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
1bd60 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
1bd70 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
1bd80 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
1bd90 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
1bda0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1bdb0 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
1bdc0 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
1bdd0 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
1bde0 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
1bdf0 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
1be00 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
1be10 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
1be20 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
1be30 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
1be40 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
1be50 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
1be60 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
1be70 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
1be80 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
1be90 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
1bea0 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
1beb0 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
1bec0 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
1bed0 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
1bee0 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
1bef0 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
1bf00 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
1bf10 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
1bf20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
1bf30 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
1bf40 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
1bf50 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
1bf60 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
1bf70 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
1bf80 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
1bf90 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
1bfa0 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
1bfb0 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
1bfc0 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
1bfd0 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
1bfe0 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
1bff0 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
1c000 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
1c010 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
1c020 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
1c030 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1c040 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
1c050 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
1c060 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
1c070 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
1c080 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
1c090 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
1c0a0 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
1c0b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
1c0c0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
1c0d0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
1c0e0 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
1c0f0 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
1c100 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
1c110 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
1c120 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1c130 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
1c140 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
1c150 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
1c160 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
1c170 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
1c180 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
1c190 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
1c1a0 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74  rowid]..*/.sqlit
1c1b0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1c1c0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1c1d0 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
1c1e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1c1f0 65 74 20 74 68 65 20 4c 61 73 74 20 49 6e 73 65  et the Last Inse
1c200 72 74 20 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a  rt Rowid value..
1c210 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1c220 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
1c230 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
1c240 73 65 72 74 5f 72 6f 77 69 64 28 44 2c 20 52 29  sert_rowid(D, R)
1c250 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74   method allows t
1c260 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
1c270 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20 76 61 6c  o.** set the val
1c280 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 63  ue returned by c
1c290 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c  alling sqlite3_l
1c2a0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1c2b0 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74  (D) to R .** wit
1c2c0 68 6f 75 74 20 69 6e 73 65 72 74 69 6e 67 20 61  hout inserting a
1c2d0 20 72 6f 77 20 69 6e 74 6f 20 74 68 65 20 64 61   row into the da
1c2e0 74 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20  tabase..*/.void 
1c2f0 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74  sqlite3_set_last
1c300 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
1c310 6c 69 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69  lite3*,sqlite3_i
1c320 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt64);../*.** CA
1c330 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
1c340 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
1c350 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54   Modified.** MET
1c360 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1c370 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1c380 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
1c390 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64  mber of rows mod
1c3a0 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20  ified, inserted 
1c3b0 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79  or.** deleted by
1c3c0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1c3d0 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
1c3e0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1c3f0 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
1c400 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  nt on the databa
1c410 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70  se connection sp
1c420 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
1c430 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  nly parameter..*
1c440 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  * ^Executing any
1c450 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
1c460 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
1c470 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65  s not modify the
1c480 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
1c490 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
1c4a0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  ion..**.** ^Only
1c4b0 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69   changes made di
1c4c0 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e  rectly by the IN
1c4d0 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
1c4e0 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
1c4f0 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
1c500 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63  ed - auxiliary c
1c510 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
1c520 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
1c530 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a   | triggers], .*
1c540 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  * [foreign key a
1c550 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c  ctions] or [REPL
1c560 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20  ACE] constraint 
1c570 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e  resolution are n
1c580 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a  ot counted..** .
1c590 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20  ** Changes to a 
1c5a0 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e  view that are in
1c5b0 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a  tercepted by .**
1c5c0 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
1c5d0 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f  gger | INSTEAD O
1c5e0 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20  F triggers] are 
1c5f0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68  not counted. ^Th
1c600 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75  e value .** retu
1c610 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1c620 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69  changes() immedi
1c630 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49  ately after an I
1c640 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
1c650 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74   .** DELETE stat
1c660 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76  ement run on a v
1c670 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65  iew is always ze
1c680 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73  ro. Only changes
1c690 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a   made to real .*
1c6a0 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75  * tables are cou
1c6b0 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e  nted..**.** Thin
1c6c0 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70  gs are more comp
1c6d0 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73  licated if the s
1c6e0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1c6f0 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
1c700 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61  executed while a
1c710 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1c720 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69   is running. Thi
1c730 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20  s may happen if 
1c740 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  the.** program u
1c750 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73  ses the [changes
1c760 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1c770 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68  , or if some oth
1c780 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  er callback.** f
1c790 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  unction invokes 
1c7a0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1c7b0 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65  ) directly. Esse
1c7c0 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20  ntially:.** .** 
1c7d0 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  <ul>.**   <li> ^
1c7e0 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67  (Before entering
1c7f0 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
1c800 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  am the value ret
1c810 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  urned by.**     
1c820 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67     sqlite3_chang
1c830 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
1c840 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68   saved. After th
1c850 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  e trigger progra
1c860 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73  m .**        has
1c870 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f   finished, the o
1c880 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73  riginal value is
1c890 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20   restored.)^.** 
1c8a0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74  .**   <li> ^(Wit
1c8b0 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72  hin a trigger pr
1c8c0 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52  ogram each INSER
1c8d0 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45  T, UPDATE and DE
1c8e0 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20  LETE .**        
1c8f0 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74  statement sets t
1c900 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1c910 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
1c920 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20  nges() .**      
1c930 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f    upon completio
1c940 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20  n as normal. Of 
1c950 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c  course, this val
1c960 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c  ue will not incl
1c970 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61  ude .**        a
1c980 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f  ny changes perfo
1c990 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67  rmed by sub-trig
1c9a0 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c  gers, as the sql
1c9b0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a  ite3_changes() .
1c9c0 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20  **        value 
1c9d0 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e  will be saved an
1c9e0 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72  d restored after
1c9f0 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65   each sub-trigge
1ca00 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20  r has run.)^.** 
1ca10 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68  </ul>.** .** ^Th
1ca20 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66  is means that if
1ca30 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53   the changes() S
1ca40 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20  QL function (or 
1ca50 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64  similar) is used
1ca60 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74  .** by the first
1ca70 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1ca80 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
1ca90 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69  ent within a tri
1caa0 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74  gger, it .** ret
1cab0 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61  urns the value a
1cac0 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63  s set when the c
1cad0 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  alling statement
1cae0 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67   began executing
1caf0 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75  ..** ^If it is u
1cb00 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  sed by the secon
1cb10 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  d or subsequent 
1cb20 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77  such statement w
1cb30 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
1cb40 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65  .** program, the
1cb50 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1cb60 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d  reflects the num
1cb70 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
1cb80 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
1cb90 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c  previous INSERT,
1cba0 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
1cbb0 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
1cbc0 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  in the same trig
1cbd0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  ger..**.** If a 
1cbe0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
1cbf0 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
1cc00 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
1cc10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1cc20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
1cc30 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
1cc40 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
1cc50 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
1cc60 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
1cc70 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
1cc80 67 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  gful..**.** See 
1cc90 61 6c 73 6f 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  also:.** <ul>.**
1cca0 20 3c 6c 69 3e 20 74 68 65 20 5b 73 71 6c 69 74   <li> the [sqlit
1ccb0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1ccc0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
1ccd0 20 3c 6c 69 3e 20 74 68 65 20 5b 63 6f 75 6e 74   <li> the [count
1cce0 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
1ccf0 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 63 68  .** <li> the [ch
1cd00 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
1cd10 74 69 6f 6e 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68  tion].** <li> th
1cd20 65 20 5b 64 61 74 61 5f 76 65 72 73 69 6f 6e 20  e [data_version 
1cd30 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 2f 75 6c 3e  pragma].** </ul>
1cd40 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1cd50 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
1cd60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1cd70 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72  EF: Total Number
1cd80 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
1cd90 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
1cda0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1cdb0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1cdc0 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  s the total numb
1cdd0 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72  er of rows inser
1cde0 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72  ted, modified or
1cdf0 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61  .** deleted by a
1ce00 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50  ll [INSERT], [UP
1ce10 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45  DATE] or [DELETE
1ce20 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d  ] statements com
1ce30 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20  pleted.** since 
1ce40 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1ce50 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e  nection was open
1ce60 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  ed, including th
1ce70 6f 73 65 20 65 78 65 63 75 74 65 64 20 61 73 0a  ose executed as.
1ce80 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67 67  ** part of trigg
1ce90 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78  er programs. ^Ex
1cea0 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65  ecuting any othe
1ceb0 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74  r type of SQL st
1cec0 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20  atement.** does 
1ced0 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 76  not affect the v
1cee0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1cef0 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
1cf00 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a  hanges()..** .**
1cf10 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61   ^Changes made a
1cf20 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69  s part of [forei
1cf30 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20  gn key actions] 
1cf40 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  are included in 
1cf50 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75  the.** count, bu
1cf60 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20  t those made as 
1cf70 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20  part of REPLACE 
1cf80 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
1cf90 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74  ution are.** not
1cfa0 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20  . ^Changes to a 
1cfb0 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e  view that are in
1cfc0 74 65 72 63 65 70 74 65 64 20 62 79 20 49 4e 53  tercepted by INS
1cfd0 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73  TEAD OF triggers
1cfe0 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75   .** are not cou
1cff0 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  nted..**.** This
1d000 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
1d010 74 61 6c 5f 63 68 61 6e 67 65 73 28 44 29 5d 20  tal_changes(D)] 
1d020 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72  interface only r
1d030 65 70 6f 72 74 73 20 74 68 65 20 6e 75 6d 62 65  eports the numbe
1d040 72 0a 2a 2a 20 6f 66 20 72 6f 77 73 20 74 68 61  r.** of rows tha
1d050 74 20 63 68 61 6e 67 65 64 20 64 75 65 20 74 6f  t changed due to
1d060 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 72   SQL statement r
1d070 75 6e 20 61 67 61 69 6e 73 74 20 64 61 74 61 62  un against datab
1d080 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
1d090 6e 20 44 2e 20 20 41 6e 79 20 63 68 61 6e 67 65  n D.  Any change
1d0a0 73 20 62 79 20 6f 74 68 65 72 20 64 61 74 61 62  s by other datab
1d0b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
1d0c0 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 20  are ignored..** 
1d0d0 54 6f 20 64 65 74 65 63 74 20 63 68 61 6e 67 65  To detect change
1d0e0 73 20 61 67 61 69 6e 73 74 20 61 20 64 61 74 61  s against a data
1d0f0 62 61 73 65 20 66 69 6c 65 20 66 72 6f 6d 20 6f  base file from o
1d100 74 68 65 72 20 64 61 74 61 62 61 73 65 0a 2a 2a  ther database.**
1d110 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 75 73 65   connections use
1d120 20 74 68 65 20 5b 50 52 41 47 4d 41 20 64 61 74   the [PRAGMA dat
1d130 61 5f 76 65 72 73 69 6f 6e 5d 20 63 6f 6d 6d 61  a_version] comma
1d140 6e 64 20 6f 72 20 74 68 65 0a 2a 2a 20 5b 53 51  nd or the.** [SQ
1d150 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f  LITE_FCNTL_DATA_
1d160 56 45 52 53 49 4f 4e 5d 20 5b 66 69 6c 65 20 63  VERSION] [file c
1d170 6f 6e 74 72 6f 6c 5d 2e 0a 2a 2a 20 0a 2a 2a 20  ontrol]..** .** 
1d180 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
1d190 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
1d1a0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
1d1b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d1c0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
1d1d0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1d1e0 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
1d1f0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
1d200 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
1d210 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
1d220 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
1d230 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1d240 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
1d250 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
1d260 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
1d270 63 65 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b  ce.** <li> the [
1d280 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
1d290 61 67 6d 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68  agma].** <li> th
1d2a0 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
1d2b0 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 3c 6c   function].** <l
1d2c0 69 3e 20 74 68 65 20 5b 64 61 74 61 5f 76 65 72  i> the [data_ver
1d2d0 73 69 6f 6e 20 70 72 61 67 6d 61 5d 0a 2a 2a 20  sion pragma].** 
1d2e0 3c 6c 69 3e 20 74 68 65 20 5b 53 51 4c 49 54 45  <li> the [SQLITE
1d2f0 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53  _FCNTL_DATA_VERS
1d300 49 4f 4e 5d 20 5b 66 69 6c 65 20 63 6f 6e 74 72  ION] [file contr
1d310 6f 6c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ol].** </ul>.*/.
1d320 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  int sqlite3_tota
1d330 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  l_changes(sqlite
1d340 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
1d350 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20  3REF: Interrupt 
1d360 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51  A Long-Running Q
1d370 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  uery.** METHOD: 
1d380 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1d390 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
1d3a0 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
1d3b0 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
1d3c0 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
1d3d0 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
1d3e0 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
1d3f0 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
1d400 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
1d410 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
1d420 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
1d430 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
1d440 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
1d450 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
1d460 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
1d470 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
1d480 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
1d490 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
1d4a0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
1d4b0 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
1d4c0 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
1d4d0 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
1d4e0 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
1d4f0 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
1d500 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
1d510 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
1d520 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
1d530 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
1d540 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
1d550 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
1d560 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1d570 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
1d580 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
1d590 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
1d5a0 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
1d5b0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
1d5c0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
1d5d0 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
1d5e0 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
1d5f0 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
1d600 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1d610 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
1d620 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
1d630 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
1d640 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
1d650 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
1d660 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
1d670 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
1d680 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
1d690 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
1d6a0 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
1d6b0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
1d6c0 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
1d6d0 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
1d6e0 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
1d6f0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
1d700 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
1d710 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
1d720 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
1d730 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
1d740 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
1d750 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
1d760 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
1d770 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
1d780 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1d790 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
1d7a0 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
1d7b0 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
1d7c0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
1d7d0 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
1d7e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1d7f0 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
1d800 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
1d810 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
1d820 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
1d830 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1d840 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
1d850 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
1d860 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
1d870 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
1d880 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
1d890 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
1d8a0 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
1d8b0 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
1d8c0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
1d8d0 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
1d8e0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1d8f0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1d900 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
1d910 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
1d920 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
1d930 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
1d940 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
1d950 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
1d960 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
1d970 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
1d980 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
1d990 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
1d9a0 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
1d9b0 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
1d9c0 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
1d9d0 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
1d9e0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
1d9f0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
1da00 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1da10 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
1da20 75 72 6e 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  urns..*/.void sq
1da30 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1da40 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1da50 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
1da60 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
1da70 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d  Statement Is Com
1da80 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73  plete.**.** Thes
1da90 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
1daa0 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d  seful during com
1dab0 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
1dac0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
1dad0 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
1dae0 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
1daf0 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f  ems to form a co
1db00 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
1db10 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
1db20 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
1db30 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
1db40 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
1db50 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
1db60 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54  for parsing.  ^T
1db70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1db80 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e  turn 1 if the in
1db90 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70  put string.** ap
1dba0 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f  pears to be a co
1dbb0 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
1dbc0 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d  ment.  ^A statem
1dbd0 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f  ent is judged to
1dbe0 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20   be.** complete 
1dbf0 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20  if it ends with 
1dc00 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65  a semicolon toke
1dc10 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  n and is not a p
1dc20 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65  refix of a.** we
1dc30 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45  ll-formed CREATE
1dc40 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
1dc50 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73  nt.  ^Semicolons
1dc60 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64   that are embedd
1dc70 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72  ed within.** str
1dc80 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20  ing literals or 
1dc90 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65  quoted identifie
1dca0 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65  r names or comme
1dcb0 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69  nts are not.** i
1dcc0 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e  ndependent token
1dcd0 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74  s (they are part
1dce0 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e   of the token in
1dcf0 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a   which they are.
1dd00 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64  ** embedded) and
1dd10 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75   thus do not cou
1dd20 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e  nt as a statemen
1dd30 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  t terminator.  ^
1dd40 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e  Whitespace.** an
1dd50 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20  d comments that 
1dd60 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c  follow the final
1dd70 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69   semicolon are i
1dd80 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gnored..**.** ^T
1dd90 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1dda0 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74  turn 0 if the st
1ddb0 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d  atement is incom
1ddc0 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a  plete.  ^If a.**
1ddd0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1dde0 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53  on fails, then S
1ddf0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72  QLITE_NOMEM is r
1de00 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
1de10 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64  These routines d
1de20 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20  o not parse the 
1de30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74  SQL statements t
1de40 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  hus.** will not 
1de50 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63  detect syntactic
1de60 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53  ally incorrect S
1de70 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53  QL..**.** ^(If S
1de80 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65  QLite has not be
1de90 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75  en initialized u
1dea0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e  sing [sqlite3_in
1deb0 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f  itialize()] prio
1dec0 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e  r .** to invokin
1ded0 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  g sqlite3_comple
1dee0 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69  te16() then sqli
1def0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
1df00 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
1df10 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
1df20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1df30 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69  16().  If that i
1df40 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61  nitialization fa
1df50 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ils,.** then the
1df60 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
1df70 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  om sqlite3_compl
1df80 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20  ete16() will be 
1df90 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61  non-zero.** rega
1dfa0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
1dfb0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70  r or not the inp
1dfc0 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65  ut SQL is comple
1dfd0 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te.)^.**.** The 
1dfe0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1dff0 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75  3_complete()] mu
1e000 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
1e010 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38  minated.** UTF-8
1e020 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
1e030 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
1e040 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1e050 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
1e060 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1e070 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
1e080 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1e090 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
1e0a0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
1e0b0 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e  t char *sql);.in
1e0c0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
1e0d0 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
1e0e0 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
1e0f0 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
1e100 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
1e110 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
1e120 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57  Y Errors.** KEYW
1e130 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64  ORDS: {busy-hand
1e140 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62  ler callback} {b
1e150 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20  usy handler}.** 
1e160 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1e170 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1e180 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1e190 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73  D,X,P) routine s
1e1a0 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ets a callback f
1e1b0 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61  unction X.** tha
1e1c0 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
1e1d0 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ed with argument
1e1e0 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61   P whenever.** a
1e1f0 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
1e200 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61  e to access a da
1e210 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73  tabase table ass
1e220 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20  ociated with.** 
1e230 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1e240 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f  tion] D when ano
1e250 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f  ther thread.** o
1e260 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68  r process has th
1e270 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a  e table locked..
1e280 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
1e290 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e  usy_handler() in
1e2a0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
1e2b0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20  to implement.** 
1e2c0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
1e2d0 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52  meout()] and [PR
1e2e0 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
1e2f0 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  t]..**.** ^If th
1e300 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
1e310 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
1e320 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69  QLITE_BUSY].** i
1e330 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
1e340 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
1e350 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
1e360 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79  k.  ^If the busy
1e370 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
1e380 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
1e390 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68  he callback migh
1e3a0 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
1e3b0 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
1e3c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
1e3d0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
1e3e0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
1e3f0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
1e400 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
1e410 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
1e420 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
1e430 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1e440 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65  dler().  ^The se
1e450 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
1e460 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
1e470 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
1e480 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
1e490 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
1e4a0 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
1e4b0 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70  * been invoked p
1e4c0 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68  reviously for th
1e4d0 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65  e same locking e
1e4e0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
1e4f0 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
1e500 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
1e510 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
1e520 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
1e530 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
1e540 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
1e550 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72  QLITE_BUSY] is r
1e560 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68  eturned.** to th
1e570 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a  e application..*
1e580 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
1e590 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
1e5a0 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
1e5b0 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
1e5c0 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74  made to access t
1e5d0 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
1e5e0 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74  the cycle repeat
1e5f0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  s..**.** The pre
1e600 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20  sence of a busy 
1e610 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74  handler does not
1e620 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
1e630 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  it will be invok
1e640 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65  ed.** when there
1e650 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74   is lock content
1e660 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ion. ^If SQLite 
1e670 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20  determines that 
1e680 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
1e690 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75  y.** handler cou
1e6a0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64  ld result in a d
1e6b0 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c  eadlock, it will
1e6c0 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65   go ahead and re
1e6d0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
1e6e0 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  Y].** to the app
1e6f0 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64  lication instead
1e700 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65   of invoking the
1e710 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65   .** busy handle
1e720 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
1e730 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
1e740 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
1e750 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
1e760 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
1e770 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
1e780 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
1e790 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
1e7a0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
1e7b0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
1e7c0 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
1e7d0 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
1e7e0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
1e7f0 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
1e800 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
1e810 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
1e820 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
1e830 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
1e840 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
1e850 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
1e860 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
1e870 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
1e880 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
1e890 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
1e8a0 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
1e8b0 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
1e8c0 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
1e8d0 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
1e8e0 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
1e8f0 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
1e900 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
1e910 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
1e920 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
1e930 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
1e940 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
1e950 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
1e960 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
1e970 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
1e980 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
1e990 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
1e9a0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
1e9b0 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
1e9c0 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  is NULL..**.** ^
1e9d0 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
1e9e0 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
1e9f0 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
1ea00 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
1ea10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ea20 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
1ea30 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
1ea40 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
1ea50 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
1ea60 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74  dler.)^  ^Note t
1ea70 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
1ea80 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1ea90 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75  t()].** or evalu
1eaa0 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75  ating [PRAGMA bu
1eab0 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69  sy_timeout=N] wi
1eac0 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  ll change the.**
1ead0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e   busy handler an
1eae0 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79  d thus clear any
1eaf0 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
1eb00 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
1eb10 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
1eb20 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
1eb30 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
1eb40 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
1eb50 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
1eb60 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
1eb70 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
1eb80 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68  handler.  In oth
1eb90 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65  er words,.** the
1eba0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1ebb0 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20   not reentrant. 
1ebc0 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
1ebd0 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
1ebe0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
1ebf0 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79  r..** .** A busy
1ec00 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
1ec10 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
1ec20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1ec30 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20  ** or [prepared 
1ec40 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
1ec50 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
1ec60 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74   handler..*/.int
1ec70 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1ec80 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 69  ndler(sqlite3*,i
1ec90 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29  nt(*)(void*,int)
1eca0 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ,void*);../*.** 
1ecb0 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20  CAPI3REF: Set A 
1ecc0 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20  Busy Timeout.** 
1ecd0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1ece0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1ecf0 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
1ed00 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1ed10 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
1ed20 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
1ed30 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
1ed40 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
1ed50 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
1ed60 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e  ocked.  ^The han
1ed70 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
1ed80 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
1ed90 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
1eda0 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
1edb0 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
1edc0 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
1edd0 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c  ed.  ^After at l
1ede0 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
1edf0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
1ee00 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
1ee10 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
1ee20 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
1ee30 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
1ee40 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
1ee50 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  BUSY]..**.** ^Ca
1ee60 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
1ee70 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
1ee80 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
1ee90 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
1eea0 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
1eeb0 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
1eec0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1eed0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1eee0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
1eef0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
1ef00 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1ef10 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20  nection] at any 
1ef20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
1ef30 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
1ef40 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
1ef50 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
1ef60 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1ef70 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
1ef80 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
1ef90 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
1efa0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
1efb0 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a  r is cleared.)^.
1efc0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
1efd0 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1efe0 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71  meout].*/.int sq
1eff0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1f000 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ut(sqlite3*, int
1f010 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   ms);../*.** CAP
1f020 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e  I3REF: Convenien
1f030 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20  ce Routines For 
1f040 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a  Running Queries.
1f050 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1f060 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e3.**.** This is
1f070 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66   a legacy interf
1f080 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73  ace that is pres
1f090 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61  erved for backwa
1f0a0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1f0b0 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69  y..** Use of thi
1f0c0 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  s interface is n
1f0d0 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  ot recommended..
1f0e0 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
1f0f0 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
1f100 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
1f110 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
1f120 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
1f130 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
1f140 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
1f150 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
1f160 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
1f170 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
1f180 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
1f190 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
1f1a0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
1f1b0 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
1f1c0 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
1f1d0 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
1f1e0 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
1f1f0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
1f200 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
1f210 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
1f220 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
1f230 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
1f240 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
1f250 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
1f260 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
1f270 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
1f280 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
1f290 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1f2a0 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
1f2b0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
1f2c0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1f2d0 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  -8 strings..** T
1f2e0 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d  here are (N+1)*M
1f2f0 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65   elements in the
1f300 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72   array.  The fir
1f310 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f  st M pointers po
1f320 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74  int.** to zero-t
1f330 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
1f340 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20  s that  contain 
1f350 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  the names of the
1f360 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65   columns..** The
1f370 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69   remaining entri
1f380 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20  es all point to 
1f390 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20  query results.  
1f3a0 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75  NULL values resu
1f3b0 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f  lt.** in NULL po
1f3c0 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68  inters.  All oth
1f3d0 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  er values are in
1f3e0 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72   their UTF-8 zer
1f3f0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1f400 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74  string represent
1f410 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65  ation as returne
1f420 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
1f430 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
1f440 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1f450 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74  le might consist
1f460 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
1f470 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1f480 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  ns..** It is not
1f490 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20   safe to pass a 
1f4a0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72  result table dir
1f4b0 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65  ectly to [sqlite
1f4c0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20  3_free()]..** A 
1f4d0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f  result table sho
1f4e0 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  uld be deallocat
1f4f0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1f500 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
1f510 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65  .**.** ^(As an e
1f520 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65  xample of the re
1f530 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61  sult table forma
1f540 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65  t, suppose a que
1f550 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  ry result.** is 
1f560 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1f570 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1f580 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61  re>.**        Na
1f590 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a  me        | Age.
1f5a0 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d  **        ------
1f5b0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1f5c0 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63  -.**        Alic
1f5d0 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20  e       | 43.** 
1f5e0 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20         Bob      
1f5f0 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20     | 28.**      
1f600 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20    Cindy       | 
1f610 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  21.** </pre></bl
1f620 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1f630 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f  There are two co
1f640 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20  lumn (M==2) and 
1f650 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33  three rows (N==3
1f660 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20  ).  Thus the.** 
1f670 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73  result table has
1f680 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70   8 entries.  Sup
1f690 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20  pose the result 
1f6a0 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a  table is stored.
1f6b0 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e  ** in an array n
1f6c0 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20  ames azResult.  
1f6d0 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f  Then azResult ho
1f6e0 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74  lds this content
1f6f0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1f700 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
1f710 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1f720 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a  ;0] = "Name";.**
1f730 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1f740 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b  &#91;1] = "Age";
1f750 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1f760 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c  ult&#91;2] = "Al
1f770 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ice";.**        
1f780 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20  azResult&#91;3] 
1f790 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20  = "43";.**      
1f7a0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34    azResult&#91;4
1f7b0 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20  ] = "Bob";.**   
1f7c0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1f7d0 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20  1;5] = "28";.** 
1f7e0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1f7f0 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22  #91;6] = "Cindy"
1f800 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1f810 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32  sult&#91;7] = "2
1f820 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  1";.** </pre></b
1f830 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
1f840 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1f850 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63  get_table() func
1f860 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f  tion evaluates o
1f870 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65  ne or more.** se
1f880 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
1f890 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
1f8a0 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   in the zero-ter
1f8b0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
1f8c0 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32   string of its 2
1f8d0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
1f8e0 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
1f8f0 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a  t table to the.*
1f900 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20  * pointer given 
1f910 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  in its 3rd param
1f920 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  eter..**.** Afte
1f930 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
1f940 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  n has finished w
1f950 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66  ith the result f
1f960 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  rom sqlite3_get_
1f970 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d  table(),.** it m
1f980 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73  ust pass the res
1f990 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65  ult table pointe
1f9a0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  r to sqlite3_fre
1f9b0 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64  e_table() in ord
1f9c0 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65  er to.** release
1f9d0 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74   the memory that
1f9e0 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20   was malloced.  
1f9f0 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77  Because of the w
1fa00 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ay the.** [sqlit
1fa10 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70  e3_malloc()] hap
1fa20 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69  pens within sqli
1fa30 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
1fa40 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20   the calling.** 
1fa50 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  function must no
1fa60 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73  t try to call [s
1fa70 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64  qlite3_free()] d
1fa80 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a  irectly.  Only.*
1fa90 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  * [sqlite3_free_
1faa0 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65  table()] is able
1fab0 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20   to release the 
1fac0 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20  memory properly 
1fad0 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a  and safely..**.*
1fae0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
1faf0 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66  t_table() interf
1fb00 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ace is implement
1fb10 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20  ed as a wrapper 
1fb20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
1fb30 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65  e3_exec()].  The
1fb40 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1fb50 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  le() routine doe
1fb60 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73  s not have acces
1fb70 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65  s.** to any inte
1fb80 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74  rnal data struct
1fb90 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ures of SQLite. 
1fba0 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68   It uses only th
1fbb0 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65  e public.** inte
1fbc0 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65  rface defined he
1fbd0 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71  re.  As a conseq
1fbe0 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68  uence, errors th
1fbf0 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a  at occur in the.
1fc00 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72  ** wrapper layer
1fc10 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
1fc20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65  internal [sqlite
1fc30 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61  3_exec()] call a
1fc40 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63  re not.** reflec
1fc50 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e  ted in subsequen
1fc60 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
1fc70 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f  te3_errcode()] o
1fc80 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  r.** [sqlite3_er
1fc90 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  rmsg()]..*/.int 
1fca0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1fcb0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
1fcc0 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e  ,          /* An
1fcd0 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
1fce0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1fcf0 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c  zSql,     /* SQL
1fd00 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
1fd10 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61   */.  char ***pa
1fd20 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52  zResult,    /* R
1fd30 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
1fd40 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ery */.  int *pn
1fd50 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Row,           /
1fd60 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1fd70 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
1fd80 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  here */.  int *p
1fd90 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  nColumn,        
1fda0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1fdb0 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
1fdc0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
1fdd0 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20  ar **pzErrmsg   
1fde0 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
1fdf0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1fe00 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .);.void sqlite3
1fe10 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
1fe20 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
1fe30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
1fe40 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
1fe50 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
1fe60 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1fe70 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61  tines are work-a
1fe80 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72  likes of the "pr
1fe90 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f  intf()" family o
1fea0 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66  f functions.** f
1feb0 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
1fec0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54   C library..** T
1fed0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e  hese routines un
1fee0 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66  derstand most of
1fef0 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 66 6f 72 6d   the common form
1ff00 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66  atting options f
1ff10 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
1ff20 61 72 64 20 6c 69 62 72 61 72 79 20 70 72 69 6e  ard library prin
1ff30 74 66 28 29 20 0a 2a 2a 20 70 6c 75 73 20 73 6f  tf() .** plus so
1ff40 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f  me additional no
1ff50 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61  n-standard forma
1ff60 74 73 20 28 5b 25 71 5d 2c 20 5b 25 51 5d 2c 20  ts ([%q], [%Q], 
1ff70 5b 25 77 5d 2c 20 61 6e 64 20 5b 25 7a 5d 29 2e  [%w], and [%z]).
1ff80 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 62 75 69  .** See the [bui
1ff90 6c 74 2d 69 6e 20 70 72 69 6e 74 66 28 29 5d 20  lt-in printf()] 
1ffa0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
1ffb0 72 20 64 65 74 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  r details..**.**
1ffc0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70   ^The sqlite3_mp
1ffd0 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69  rintf() and sqli
1ffe0 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72  te3_vmprintf() r
1fff0 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68  outines write th
20000 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  eir.** results i
20010 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
20020 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
20030 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d 2e 0a 2a  3_malloc64()]..*
20040 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
20050 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
20060 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
20070 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
20080 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
20090 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72  ree()].  ^Both r
200a0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
200b0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
200c0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
200d0 6c 6f 63 36 34 28 29 5d 20 69 73 20 75 6e 61 62  loc64()] is unab
200e0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
200f0 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
20100 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
20110 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
20120 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
20130 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
20140 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
20150 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
20160 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
20170 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
20180 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
20190 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
201a0 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
201b0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
201c0 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
201d0 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
201e0 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
201f0 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
20200 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
20210 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
20220 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
20230 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
20240 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
20250 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
20260 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
20270 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
20280 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
20290 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
202a0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
202b0 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
202c0 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
202d0 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
202e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
202f0 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
20300 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
20310 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
20320 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
20330 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
20340 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
20350 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
20360 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
20370 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
20380 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
20390 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
203a0 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
203b0 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
203c0 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
203d0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
203e0 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
203f0 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
20400 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
20410 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
20420 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
20430 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
20440 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
20450 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
20460 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
20470 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
20480 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
20490 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
204a0 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
204b0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
204c0 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
204d0 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
204e0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
204f0 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
20500 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
20510 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
20520 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
20530 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
20540 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
20550 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
20560 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
20570 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
20580 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
20590 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  f()..**.** See a
205a0 6c 73 6f 3a 20 20 5b 62 75 69 6c 74 2d 69 6e 20  lso:  [built-in 
205b0 70 72 69 6e 74 66 28 29 5d 2c 20 5b 70 72 69 6e  printf()], [prin
205c0 74 66 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  tf() SQL functio
205d0 6e 5d 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69  n].*/.char *sqli
205e0 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
205f0 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68  t char*,...);.ch
20600 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
20610 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
20620 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72  , va_list);.char
20630 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   *sqlite3_snprin
20640 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
20650 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
20660 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73  char *sqlite3_vs
20670 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
20680 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  *,const char*, v
20690 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  a_list);../*.** 
206a0 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
206b0 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
206c0 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
206d0 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
206e0 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
206f0 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
20700 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
20710 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
20720 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
20730 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
20740 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
20750 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
20760 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
20770 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
20780 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
20790 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
207a0 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
207b0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
207c0 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
207d0 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
207e0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
207f0 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
20800 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
20810 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
20820 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
20830 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
20840 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
20850 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
20860 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
20870 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
20880 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
20890 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
208a0 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
208b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
208c0 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
208d0 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
208e0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
208f0 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
20900 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
20910 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
20920 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
20930 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
20940 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72  e3_malloc64(N) r
20950 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73  outine works jus
20960 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  t like.** sqlite
20970 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65  3_malloc(N) exce
20980 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20  pt that N is an 
20990 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20  unsigned 64-bit 
209a0 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a  integer instead.
209b0 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33  ** of a signed 3
209c0 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a  2-bit integer..*
209d0 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  *.** ^Calling sq
209e0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
209f0 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
20a00 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
20a10 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
20a20 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
20a30 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
20a40 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
20a50 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
20a60 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
20a70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72   ^The sqlite3_fr
20a80 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
20a90 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
20aa0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
20ab0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
20ac0 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
20ad0 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
20ae0 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
20af0 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
20b00 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
20b10 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
20b20 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
20b30 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
20b40 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
20b50 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
20b60 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
20b70 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
20b80 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
20b90 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
20ba0 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
20bb0 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
20bc0 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
20bd0 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
20be0 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
20bf0 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
20c00 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
20c10 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
20c20 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
20c30 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
20c40 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
20c50 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
20c60 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  alloc()..**.** ^
20c70 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
20c80 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61  loc(X,N) interfa
20c90 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
20ca0 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
20cb0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
20cc0 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65  on X to be at le
20cd0 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20  ast N bytes..** 
20ce0 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d 65  ^If the X parame
20cf0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
20d00 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69  ealloc(X,N).** i
20d10 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
20d20 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
20d30 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
20d40 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
20d50 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e  lite3_malloc(N).
20d60 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61  .** ^If the N pa
20d70 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
20d80 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
20d90 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65  is zero or.** ne
20da0 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20  gative then the 
20db0 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63  behavior is exac
20dc0 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20  tly the same as 
20dd0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
20de0 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e  e3_free(X)..** ^
20df0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
20e00 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70  X,N) returns a p
20e10 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
20e20 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
20e30 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
20e40 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
20e50 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63  NULL if insuffic
20e60 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61  ient memory is a
20e70 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
20e80 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
20e90 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
20ea0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
20eb0 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
20ec0 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
20ed0 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
20ee0 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
20ef0 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
20f00 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
20f10 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
20f20 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  N) and the prior
20f30 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
20f40 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  reed..** ^If sql
20f50 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
20f60 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61  ) returns NULL a
20f70 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65  nd N is positive
20f80 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72  , then the.** pr
20f90 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
20fa0 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
20fb0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
20fc0 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69  realloc64(X,N) i
20fd0 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20  nterfaces works 
20fe0 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73  the same as.** s
20ff0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
21000 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  ,N) except that 
21010 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e  N is a 64-bit un
21020 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69  signed integer i
21030 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33  nstead.** of a 3
21040 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  2-bit signed int
21050 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  eger..**.** ^If 
21060 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c  X is a memory al
21070 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75  location previou
21080 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
21090 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
210a0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  (),.** sqlite3_m
210b0 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74  alloc64(), sqlit
210c0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72  e3_realloc(), or
210d0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
210e0 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  64(), then.** sq
210f0 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72  lite3_msize(X) r
21100 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20  eturns the size 
21110 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61  of that memory a
21120 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74  llocation in byt
21130 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  es..** ^The valu
21140 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
21150 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d  lite3_msize(X) m
21160 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74  ight be larger t
21170 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a  han the number.*
21180 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 65  * of bytes reque
21190 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 20  sted when X was 
211a0 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20  allocated.  ^If 
211b0 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  X is a NULL poin
211c0 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ter then.** sqli
211d0 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
211e0 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58  urns zero.  If X
211f0 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74   points to somet
21200 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74  hing that is not
21210 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  .** the beginnin
21220 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  g of memory allo
21230 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74  cation, or if it
21240 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72   points to a for
21250 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d  merly.** valid m
21260 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
21270 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65   that has now be
21280 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74  en freed, then t
21290 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
212a0 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  f sqlite3_msize(
212b0 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  X) is undefined 
212c0 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72  and possibly har
212d0 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mful..**.** ^The
212e0 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
212f0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
21300 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  oc(), sqlite3_re
21310 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
21320 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
21330 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
21340 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c  loc64().** is al
21350 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
21360 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
21370 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20  te boundary, or 
21380 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62  to a.** 4 byte b
21390 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b  oundary if the [
213a0 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c  SQLITE_4_BYTE_AL
213b0 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f  IGNED_MALLOC] co
213c0 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
213d0 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
213e0 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
213f0 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
21400 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
21410 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
21420 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
21430 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
21440 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
21450 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
21460 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
21470 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
21480 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
21490 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
214a0 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
214b0 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
214c0 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
214d0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
214e0 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e  ors can be used.
214f0 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20  .**.** Prior to 
21500 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
21510 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f  .7.10, the Windo
21520 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  ws OS interface 
21530 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20  layer called.** 
21540 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
21550 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
21560 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
21570 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
21580 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
21590 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
215a0 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
215b0 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
215c0 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
215d0 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
215e0 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
215f0 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
21600 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
21610 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65  cation errors we
21620 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
21630 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65  .** they were re
21640 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b  ported back as [
21650 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
21660 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   or.** [SQLITE_I
21670 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61  OERR] rather tha
21680 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
21690 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ..**.** The poin
216a0 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ter arguments to
216b0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
216c0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
216d0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73  ealloc()].** mus
216e0 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c  t be either NULL
216f0 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72   or else pointer
21700 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
21710 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63  a prior.** invoc
21720 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
21730 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
21740 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
21750 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20  )] that have.** 
21760 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c  not yet been rel
21770 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eased..**.** The
21780 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
21790 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72  t not read or wr
217a0 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a  ite any part of.
217b0 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  ** a block of me
217c0 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61  mory after it ha
217d0 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20  s been released 
217e0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
217f0 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
21800 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
21810 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
21820 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
21830 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
21840 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75  lloc64(sqlite3_u
21850 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71  int64);.void *sq
21860 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
21870 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
21880 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
21890 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  64(void*, sqlite
218a0 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  3_uint64);.void 
218b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
218c0 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e  d*);.sqlite3_uin
218d0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  t64 sqlite3_msiz
218e0 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
218f0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
21900 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
21910 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
21920 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
21930 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
21940 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
21950 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
21960 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
21970 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
21980 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
21990 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
219a0 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
219b0 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
219c0 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
219d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
219e0 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
219f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
21a00 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
21a10 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
21a20 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
21a30 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
21a40 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
21a50 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
21a60 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
21a70 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
21a80 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
21a90 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
21aa0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
21ab0 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
21ac0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
21ad0 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
21ae0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
21af0 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
21b00 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
21b10 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
21b20 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
21b30 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
21b40 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
21b50 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
21b60 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
21b70 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
21b80 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
21b90 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
21ba0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
21bb0 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
21bc0 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
21bd0 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
21be0 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
21bf0 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
21c00 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
21c10 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
21c20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
21c30 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
21c40 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
21c50 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
21c60 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
21c70 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
21c80 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
21c90 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
21ca0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
21cb0 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
21cc0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
21cd0 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
21ce0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
21cf0 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
21d00 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
21d10 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
21d20 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  t..*/.sqlite3_in
21d30 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
21d40 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73  ry_used(void);.s
21d50 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
21d60 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
21d70 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
21d80 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
21d90 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
21da0 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
21db0 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
21dc0 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
21dd0 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
21de0 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
21df0 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
21e00 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
21e10 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
21e20 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
21e30 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
21e40 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
21e50 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
21e60 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
21e70 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
21e80 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
21e90 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
21ea0 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
21eb0 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
21ec0 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
21ed0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
21ee0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
21ef0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
21f00 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
21f10 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
21f20 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
21f30 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
21f40 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
21f50 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
21f60 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
21f70 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50  fer P..** ^The P
21f80 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62   parameter can b
21f90 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
21fa0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73  ..**.** ^If this
21fb0 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74   routine has not
21fc0 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79   been previously
21fd0 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68   called or if th
21fe0 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61  e previous.** ca
21ff0 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68  ll had N less th
22000 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c  an one or a NULL
22010 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20   pointer for P, 
22020 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73  then the PRNG is
22030 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67  .** seeded using
22040 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
22050 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52  ined from the xR
22060 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64  andomness method
22070 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75   of.** the defau
22080 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
22090 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20   object..** ^If 
220a0 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
220b0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
220c0 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20  e had an N of 1 
220d0 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a  or more and a.**
220e0 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e   non-NULL P then
220f0 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
22100 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
22110 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
22120 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
22130 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
22140 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
22150 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
22160 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
22170 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
22180 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
22190 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
221a0 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
221b0 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
221c0 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
221d0 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45 59 57 4f  sqlite3.** KEYWO
221e0 52 44 53 3a 20 7b 61 75 74 68 6f 72 69 7a 65 72  RDS: {authorizer
221f0 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a   callback}.**.**
22200 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
22210 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
22220 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
22230 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
22240 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
22250 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
22260 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
22270 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
22280 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
22290 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
222a0 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
222b0 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
222c0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
222d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
222e0 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
222f0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
22300 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
22310 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
22320 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
22330 65 70 61 72 65 31 36 28 29 5d 2c 20 5b 73 71 6c  epare16()], [sql
22340 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
22350 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71  2()],.** and [sq
22360 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
22370 76 33 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69  v3()].  ^At vari
22380 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
22390 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
223a0 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
223b0 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
223c0 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
223d0 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
223e0 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
223f0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
22400 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
22410 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
22420 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
22430 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  .  ^The authoriz
22440 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
22450 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
22460 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
22470 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
22480 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
22490 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
224a0 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
224b0 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
224c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
224d0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
224e0 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
224f0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
22500 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
22510 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
22520 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
22530 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
22540 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
22550 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
22560 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
22570 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
22580 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
22590 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
225a0 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
225b0 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
225c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
225d0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
225e0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
225f0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
22600 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
22610 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
22620 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
22630 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
22640 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
22650 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
22660 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
22670 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e  uested is ok.  ^
22680 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
22690 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
226a0 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
226b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
226c0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
226d0 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
226e0 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
226f0 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
22700 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
22710 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
22720 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
22730 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
22740 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
22750 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
22760 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
22770 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
22780 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
22790 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
227a0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
227b0 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
227c0 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e  face. ^The secon
227d0 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
227e0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
227f0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
22800 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
22810 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
22820 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
22830 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
22840 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
22850 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68  d. ^The third th
22860 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
22870 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
22880 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 65 69   callback are ei
22890 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ther NULL pointe
228a0 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65 72 6d 69  rs or zero-termi
228b0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a  nated strings.**
228c0 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
228d0 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73  ditional details
228e0 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
228f0 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
22900 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  ed..** Applicati
22910 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61 79 73 20  ons must always 
22920 62 65 20 70 72 65 70 61 72 65 64 20 74 6f 20 65  be prepared to e
22930 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55 4c 4c 20  ncounter a NULL 
22940 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e 79 0a 2a  pointer in any.*
22950 2a 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 74  * of the third t
22960 68 72 6f 75 67 68 20 74 68 65 20 73 69 78 74 68  hrough the sixth
22970 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
22980 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
22990 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
229a0 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
229b0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
229c0 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
229d0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
229e0 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
229f0 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
22a00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22a10 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
22a20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
22a30 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
22a40 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
22a50 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
22a60 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
22a70 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
22a80 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
22a90 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
22aa0 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
22ab0 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
22ac0 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
22ad0 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
22ae0 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
22af0 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
22b00 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
22b10 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e 20  table..** ^When 
22b20 61 20 74 61 62 6c 65 20 69 73 20 72 65 66 65 72  a table is refer
22b30 65 6e 63 65 64 20 62 79 20 61 20 5b 53 45 4c 45  enced by a [SELE
22b40 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f 6c 75 6d  CT] but no colum
22b50 6e 20 76 61 6c 75 65 73 20 61 72 65 0a 2a 2a 20  n values are.** 
22b60 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 20 74  extracted from t
22b70 68 61 74 20 74 61 62 6c 65 20 28 66 6f 72 20 65  hat table (for e
22b80 78 61 6d 70 6c 65 20 69 6e 20 61 20 71 75 65 72  xample in a quer
22b90 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c 45 43  y like.** "SELEC
22ba0 54 20 63 6f 75 6e 74 28 2a 29 20 46 52 4f 4d 20  T count(*) FROM 
22bb0 74 61 62 22 29 20 74 68 65 6e 20 74 68 65 20 5b  tab") then the [
22bc0 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 75 74  SQLITE_READ] aut
22bd0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
22be0 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  .** is invoked o
22bf0 6e 63 65 20 66 6f 72 20 74 68 61 74 20 74 61 62  nce for that tab
22c00 6c 65 20 77 69 74 68 20 61 20 63 6f 6c 75 6d 6e  le with a column
22c10 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 61 6e   name that is an
22c20 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a   empty string..*
22c30 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
22c40 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
22c50 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
22c60 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
22c70 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
22c80 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
22c90 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
22ca0 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
22cb0 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
22cc0 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
22cd0 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
22ce0 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
22cf0 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
22d00 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
22d10 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
22d20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22d30 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
22d40 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
22d50 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
22d60 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
22d70 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
22d80 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
22d90 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
22da0 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
22db0 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
22dc0 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
22dd0 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
22de0 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
22df0 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
22e00 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
22e10 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
22e20 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
22e30 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
22e40 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
22e50 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
22e60 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
22e70 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
22e80 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
22e90 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
22ea0 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
22eb0 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
22ec0 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
22ed0 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
22ee0 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
22ef0 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
22f00 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
22f10 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
22f20 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
22f30 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
22f40 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
22f50 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
22f60 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
22f70 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
22f80 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
22f90 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
22fa0 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
22fb0 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
22fc0 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
22fd0 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
22fe0 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
22ff0 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
23000 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
23010 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
23020 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
23030 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
23040 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
23050 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
23060 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
23070 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
23080 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
23090 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73  **.** ^(Only a s
230a0 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
230b0 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
230c0 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
230d0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
230e0 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
230f0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
23100 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
23110 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
23120 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20  evious call.)^  
23130 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74  ^Disable the aut
23140 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
23150 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
23160 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
23170 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
23180 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
23190 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
231a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
231b0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
231c0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
231d0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
231e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
231f0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
23200 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
23210 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
23220 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
23230 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
23240 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
23250 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
23260 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
23270 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
23280 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
23290 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
232a0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57  agraph..**.** ^W
232b0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
232c0 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73  pare_v2()] is us
232d0 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
232e0 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
232f0 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
23300 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64  t be re-prepared
23310 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
23320 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
23330 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
23340 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
23350 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
23360 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
23370 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
23380 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
23390 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
233a0 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
233b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
233c0 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
233d0 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
233e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
233f0 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
23400 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
23410 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
23420 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
23430 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
23440 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
23450 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
23460 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
23470 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
23480 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
23490 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
234a0 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
234b0 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
234c0 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
234d0 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65  epare_v2() to re
234e0 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
234f0 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
23500 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e  ma change..*/.in
23510 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
23520 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
23530 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
23540 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
23550 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
23560 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
23570 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
23580 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
23590 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
235a0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
235b0 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a  r Return Codes.*
235c0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
235d0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
235e0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
235f0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
23600 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
23610 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
23620 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
23630 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
23640 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
23650 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
23660 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
23670 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
23680 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
23690 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
236a0 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
236b0 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
236c0 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
236d0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
236e0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ion..**.** Note 
236f0 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f  that SQLITE_IGNO
23700 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  RE is also used 
23710 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72  as a [conflict r
23720 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a  esolution mode].
23730 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ** returned from
23740 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74   the [sqlite3_vt
23750 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
23760 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
23770 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
23780 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
23790 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
237a0 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
237b0 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
237c0 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
237d0 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
237e0 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
237f0 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
23800 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
23810 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
23820 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
23830 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
23840 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
23850 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
23860 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
23870 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
23880 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
23890 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
238a0 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
238b0 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
238c0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
238d0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
238e0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
238f0 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
23900 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
23910 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
23920 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
23930 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
23940 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
23950 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
23960 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
23970 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
23980 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
23990 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
239a0 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
239b0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
239c0 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
239d0 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
239e0 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
239f0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
23a00 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
23a10 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
23a20 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
23a30 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
23a40 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
23a50 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
23a60 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
23a70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
23a80 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
23a90 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
23aa0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
23ab0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
23ac0 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
23ad0 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
23ae0 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
23af0 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
23b00 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
23b10 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
23b20 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
23b30 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
23b40 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
23b50 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
23b60 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
23b70 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
23b80 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
23b90 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
23ba0 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
23bb0 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
23bc0 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
23bd0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
23be0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
23bf0 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
23c00 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
23c10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
23c20 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
23c30 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
23c40 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
23c50 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
23c60 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
23c70 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
23c80 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
23c90 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
23ca0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
23cb0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
23cc0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
23cd0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
23ce0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
23cf0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
23d00 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23d10 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
23d20 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
23d30 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
23d40 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
23d50 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23d60 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
23d70 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
23d80 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
23d90 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
23da0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23db0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
23dc0 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
23dd0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
23de0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
23df0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23e00 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
23e10 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
23e20 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
23e30 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
23e40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23e50 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
23e60 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
23e70 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
23e80 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
23e90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23ea0 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
23eb0 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
23ec0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
23ed0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
23ee0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23ef0 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
23f00 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
23f10 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
23f20 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
23f30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23f40 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
23f50 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
23f60 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
23f70 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
23f80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
23f90 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
23fa0 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
23fb0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
23fc0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
23fd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
23fe0 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
23ff0 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
24000 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
24010 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
24020 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
24030 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
24040 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
24050 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
24060 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
24070 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
24080 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
24090 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
240a0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
240b0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
240c0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
240d0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
240e0 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
240f0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
24100 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
24110 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
24120 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
24130 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
24140 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
24150 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
24160 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
24170 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
24180 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
24190 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
241a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
241b0 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
241c0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
241d0 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
241e0 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
241f0 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
24200 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
24210 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
24220 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
24230 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
24240 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
24250 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
24260 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
24270 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
24280 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
24290 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
242a0 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
242b0 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
242c0 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
242d0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
242e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
242f0 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
24300 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
24310 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
24320 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
24330 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24340 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
24350 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
24360 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
24370 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
24380 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24390 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
243a0 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
243b0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
243c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
243d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
243e0 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
243f0 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
24400 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
24410 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
24420 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24430 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
24440 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
24450 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
24460 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
24470 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
24480 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
24490 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
244a0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
244b0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
244c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
244d0 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
244e0 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
244f0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
24500 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
24510 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
24520 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
24530 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
24540 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
24550 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
24560 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
24570 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
24580 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
24590 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
245a0 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
245b0 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
245c0 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
245d0 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
245e0 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
245f0 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
24600 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
24610 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24620 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
24630 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
24640 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56   SQLITE_RECURSIV
24650 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20  E            33 
24660 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
24670 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
24680 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43       */../*.** C
24690 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
246a0 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
246b0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48  unctions.** METH
246c0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
246d0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
246e0 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e   are deprecated.
246f0 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
24700 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e  3_trace_v2()] in
24710 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65  terface.** inste
24720 61 64 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e  ad of the routin
24730 65 73 20 64 65 73 63 72 69 62 65 64 20 68 65 72  es described her
24740 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e..**.** These r
24750 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
24760 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
24770 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
24780 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
24790 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
247a0 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
247b0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
247c0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  s..**.** ^The ca
247d0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
247e0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
247f0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
24800 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
24810 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
24820 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
24830 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
24840 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
24850 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
24860 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
24870 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
24880 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65   with a UTF-8 re
24890 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a  ndering of the.*
248a0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
248b0 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74  text as the stat
248c0 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
248d0 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  ns executing..**
248e0 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71   ^(Additional sq
248f0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
24900 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63  llbacks might oc
24910 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
24920 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
24930 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
24940 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
24950 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
24960 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
24970 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
24980 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
24990 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  rigger.)^.**.** 
249a0 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  The [SQLITE_TRAC
249b0 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f  E_SIZE_LIMIT] co
249c0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
249d0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
249e0 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65   limit.** the le
249f0 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70  ngth of [bound p
24a00 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73  arameter] expans
24a10 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75  ion in the outpu
24a20 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61  t of sqlite3_tra
24a30 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ce()..**.** ^The
24a40 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
24a50 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
24a60 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
24a70 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
24a80 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
24a90 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
24aa0 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
24ab0 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
24ac0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
24ad0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
24ae0 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
24af0 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
24b00 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
24b10 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
24b20 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e   took to run.  ^
24b30 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
24b40 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20  back.** time is 
24b50 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f  in units of nano
24b60 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72  seconds, however
24b70 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
24b80 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
24b90 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f  s only capable o
24ba0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65  f millisecond re
24bb0 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20  solution so the 
24bc0 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66  six least signif
24bd0 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20  icant.** digits 
24be0 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20  in the time are 
24bf0 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75  meaningless.  Fu
24c00 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
24c10 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74   SQLite.** might
24c20 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72   provide greater
24c30 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74   resolution on t
24c40 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c  he profiler call
24c50 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71  back.  The.** sq
24c60 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
24c70 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73  function is cons
24c80 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
24c90 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75  tal and is.** su
24ca0 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
24cb0 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
24cc0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
24cd0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
24ce0 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  ED void *sqlite3
24cf0 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
24d00 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 61 63 65  .   void(*xTrace
24d10 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
24d20 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
24d30 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
24d40 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
24d50 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
24d60 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
24d70 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
24d80 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
24d90 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
24da0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
24db0 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20 43  QL Trace Event C
24dc0 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
24dd0 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a  : SQLITE_TRACE.*
24de0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
24df0 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63 6c  ants identify cl
24e00 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73 20  asses of events 
24e10 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69  that can be moni
24e20 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74  tored.** using t
24e30 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  he [sqlite3_trac
24e40 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67 20  e_v2()] tracing 
24e50 6c 6f 67 69 63 2e 20 20 54 68 65 20 4d 20 61 72  logic.  The M ar
24e60 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71  gument.** to [sq
24e70 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44  lite3_trace_v2(D
24e80 2c 4d 2c 58 2c 50 29 5d 20 69 73 20 61 6e 20 4f  ,M,X,P)] is an O
24e90 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  R-ed combination
24ea0 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
24eb0 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
24ec0 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20  ing constants.  
24ed0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
24ee0 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65  ent to the trace
24ef0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
24f00 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
24f10 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a  wing constants..
24f20 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e  **.** New tracin
24f30 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20  g constants may 
24f40 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
24f50 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a  re releases..**.
24f60 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c  ** ^A trace call
24f70 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20 61 72  back has four ar
24f80 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61  guments: xCallba
24f90 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20  ck(T,C,P,X)..** 
24fa0 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20  ^The T argument 
24fb0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e  is one of the in
24fc0 74 65 67 65 72 20 74 79 70 65 20 63 6f 64 65 73  teger type codes
24fd0 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20   above..** ^The 
24fe0 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  C argument is a 
24ff0 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
25000 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61 73 73  ext pointer pass
25010 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
25020 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
25030 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  to [sqlite3_trac
25040 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  e_v2()]..** The 
25050 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74  P and X argument
25060 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77  s are pointers w
25070 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65  hose meanings de
25080 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a  pend on T..**.**
25090 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
250a0 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c  E_TRACE_STMT]] <
250b0 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  dt>SQLITE_TRACE_
250c0 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  STMT</dt>.** <dd
250d0 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43  >^An SQLITE_TRAC
250e0 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20  E_STMT callback 
250f0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
25100 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
25110 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62 65  ment.** first be
25120 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  gins running and
25130 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f 74 68   possibly at oth
25140 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e 67 20  er times during 
25150 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e  the.** execution
25160 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64   of the prepared
25170 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75 63 68   statement, such
25180 20 61 73 20 61 74 20 74 68 65 20 73 74 61 72 74   as at the start
25190 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72 69 67   of each.** trig
251a0 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 20  ger subprogram. 
251b0 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
251c0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
251d0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
251e0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68   statement]. ^Th
251f0 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e X argument is 
25200 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73  a pointer to a s
25210 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69  tring which.** i
25220 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64 65 64  s the unexpanded
25230 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74 68 65   SQL text of the
25240 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
25250 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f  ent or an SQL co
25260 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69  mment .** that i
25270 6e 64 69 63 61 74 65 73 20 74 68 65 20 69 6e 76  ndicates the inv
25280 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74 72 69  ocation of a tri
25290 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c  gger.  ^The call
252a0 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65  back can compute
252b0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 65 78  .** the same tex
252c0 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  t that would hav
252d0 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 20  e been returned 
252e0 62 79 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  by the legacy [s
252f0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 0a  qlite3_trace()].
25300 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  ** interface by 
25310 75 73 69 6e 67 20 74 68 65 20 58 20 61 72 67 75  using the X argu
25320 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65 67 69  ment when X begi
25330 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61 6e 64  ns with "--" and
25340 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71   invoking.** [sq
25350 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
25360 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69 73 65  ql(P)] otherwise
25370 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
25380 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d  _TRACE_PROFILE]]
25390 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
253a0 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a  E_PROFILE</dt>.*
253b0 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45  * <dd>^An SQLITE
253c0 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63  _TRACE_PROFILE c
253d0 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64 65 73  allback provides
253e0 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 74   approximately t
253f0 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72  he same.** infor
25400 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70 72 6f  mation as is pro
25410 76 69 64 65 64 20 62 79 20 74 68 65 20 5b 73 71  vided by the [sq
25420 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d  lite3_profile()]
25430 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54   callback..** ^T
25440 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
25450 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
25460 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
25470 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a  ement] and the.*
25480 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  * X argument poi
25490 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69 74 20  nts to a 64-bit 
254a0 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
254b0 20 74 68 65 20 65 73 74 69 6d 61 74 65 64 20 6f   the estimated o
254c0 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  f.** the number 
254d0 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68  of nanosecond th
254e0 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  at the prepared 
254f0 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74  statement took t
25500 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53  o run..** ^The S
25510 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46  QLITE_TRACE_PROF
25520 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ILE callback is 
25530 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
25540 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
25550 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  hes..**.** [[SQL
25560 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20  ITE_TRACE_ROW]] 
25570 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45  <dt>SQLITE_TRACE
25580 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ROW</dt>.** <dd
25590 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43  >^An SQLITE_TRAC
255a0 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69  E_ROW callback i
255b0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  s invoked whenev
255c0 65 72 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a  er a prepared.**
255d0 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72   statement gener
255e0 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20 72 6f  ates a single ro
255f0 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a  w of result.  .*
25600 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  * ^The P argumen
25610 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
25620 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
25630 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74  statement] and t
25640 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74  he.** X argument
25650 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a   is unused..**.*
25660 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  * [[SQLITE_TRACE
25670 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c  _CLOSE]] <dt>SQL
25680 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c  ITE_TRACE_CLOSE<
25690 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20  /dt>.** <dd>^An 
256a0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f  SQLITE_TRACE_CLO
256b0 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  SE callback is i
256c0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 64 61  nvoked when a da
256d0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
256e0 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20  tion closes..** 
256f0 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
25700 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
25710 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
25720 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74  nnection] object
25730 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20 61 72  .** and the X ar
25740 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64  gument is unused
25750 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ..** </dl>.*/.#d
25760 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
25770 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20 30 78  CE_STMT       0x
25780 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
25790 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20  E_TRACE_PROFILE 
257a0 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20     0x02.#define 
257b0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57  SQLITE_TRACE_ROW
257c0 20 20 20 20 20 20 20 20 30 78 30 34 0a 23 64 65          0x04.#de
257d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43  fine SQLITE_TRAC
257e0 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30 78 30  E_CLOSE      0x0
257f0 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  8../*.** CAPI3RE
25800 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48 6f 6f  F: SQL Trace Hoo
25810 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  k.** METHOD: sql
25820 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
25830 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
25840 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,M,X,P) interf
25850 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
25860 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  trace callback.*
25870 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61 67 61  * function X aga
25880 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65 20 63  inst [database c
25890 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73  onnection] D, us
258a0 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d 61 73  ing property mas
258b0 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65  k M.** and conte
258c0 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e  xt pointer P.  ^
258d0 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62 61 63  If the X callbac
258e0 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20  k is.** NULL or 
258f0 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20 69 73  if the M mask is
25900 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 61 63   zero, then trac
25910 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ing is disabled.
25920 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d    The.** M argum
25930 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
25940 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65 64 20  e bitwise OR-ed 
25950 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
25960 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b  * zero or more [
25970 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20 63 6f  SQLITE_TRACE] co
25980 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  nstants..**.** ^
25990 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65 69 74  Each call to eit
259a0 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63  her sqlite3_trac
259b0 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74  e() or sqlite3_t
259c0 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72 72 69  race_v2() overri
259d0 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73  des .** (cancels
259e0 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c  ) any prior call
259f0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61  s to sqlite3_tra
25a00 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  ce() or sqlite3_
25a10 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  trace_v2()..**.*
25a20 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62 61 63  * ^The X callbac
25a30 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
25a40 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74 68 65  never any of the
25a50 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69 66 69   events identifi
25a60 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d  ed by .** mask M
25a70 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20 69 6e   occur.  ^The in
25a80 74 65 67 65 72 20 72 65 74 75 72 6e 20 76 61 6c  teger return val
25a90 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c  ue from the call
25aa0 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e 74 6c  back is currentl
25ab0 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68  y.** ignored, th
25ac0 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20 63 68  ough this may ch
25ad0 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 72  ange in future r
25ae0 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c 62 61  eleases.  Callba
25af0 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ck.** implementa
25b00 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65 74  tions should ret
25b10 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75  urn zero to ensu
25b20 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70 61 74  re future compat
25b30 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ibility..**.** ^
25b40 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  A trace callback
25b50 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
25b60 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a   four arguments:
25b70 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c   callback(T,C,P,
25b80 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72  X)..** ^The T ar
25b90 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
25ba0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41   the [SQLITE_TRA
25bb0 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73  CE].** constants
25bc0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 79   to indicate why
25bd0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61   the callback wa
25be0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54  s invoked..** ^T
25bf0 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73  he C argument is
25c00 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63   a copy of the c
25c10 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a  ontext pointer..
25c20 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 61  ** The P and X a
25c30 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69  rguments are poi
25c40 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e  nters whose mean
25c50 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54  ings depend on T
25c60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
25c70 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 69  te3_trace_v2() i
25c80 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
25c90 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63 65 20  nded to replace 
25ca0 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
25cb0 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
25cc0 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64 20 5b  3_trace()] and [
25cd0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
25ce0 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68 69 63  )], both of whic
25cf0 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65 63 61  h.** are depreca
25d00 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ted..*/.int sqli
25d10 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a 20 20  te3_trace_v2(.  
25d20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69  sqlite3*,.  unsi
25d30 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e  gned uMask,.  in
25d40 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e  t(*xCallback)(un
25d50 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69  signed,void*,voi
25d60 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69  d*,void*),.  voi
25d70 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a  d *pCtx.);../*.*
25d80 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
25d90 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
25da0 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
25db0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
25dc0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  he sqlite3_progr
25dd0 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c  ess_handler(D,N,
25de0 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63  X,P) interface c
25df0 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61  auses the callba
25e00 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
25e10 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70   to be invoked p
25e20 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
25e30 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
25e40 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
25e50 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
25e60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
25e70 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  nd [sqlite3_get_
25e80 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20  table()] for.** 
25e90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25ea0 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70  ion D.  An examp
25eb0 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a  le use for this.
25ec0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
25ed0 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
25ee0 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
25ef0 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
25f00 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72  * ^The parameter
25f10 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72   P is passed thr
25f20 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79  ough as the only
25f30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
25f40 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  e .** callback f
25f50 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65  unction X.  ^The
25f60 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20   parameter N is 
25f70 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20  the approximate 
25f80 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76  number of .** [v
25f90 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69  irtual machine i
25fa0 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61  nstructions] tha
25fb0 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t are evaluated 
25fc0 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69  between successi
25fd0 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  ve.** invocation
25fe0 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  s of the callbac
25ff0 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c  k X.  ^If N is l
26000 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65  ess than one the
26010 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a  n the progress.*
26020 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73  * handler is dis
26030 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  abled..**.** ^On
26040 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
26050 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79  ress handler may
26060 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f   be defined at o
26070 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b  ne time per.** [
26080 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
26090 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20  ion]; setting a 
260a0 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e  new progress han
260b0 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65  dler cancels the
260c0 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53  .** old one.  ^S
260d0 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72  etting parameter
260e0 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62   X to NULL disab
260f0 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73  les the progress
26100 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68   handler..** ^Th
26110 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
26120 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62  er is also disab
26130 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e  led by setting N
26140 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73   to a value less
26150 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a  .** than 1..**.*
26160 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65  * ^If the progre
26170 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
26180 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
26190 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
261a0 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
261b0 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
261c0 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
261d0 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
261e0 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
261f0 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61  GUI progress dia
26200 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54  log box..**.** T
26210 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
26220 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  ler callback mus
26230 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
26240 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
26250 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
26260 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
26270 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
26280 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
26290 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
262a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
262b0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
262c0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
262d0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
262e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
262f0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
26300 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
26310 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
26320 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71  h..**.*/.void sq
26330 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
26340 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
26350 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
26360 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
26370 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
26380 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
26390 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
263a0 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20  ** CONSTRUCTOR: 
263b0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
263c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
263d0 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
263e0 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70  abase file as sp
263f0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ecified by the .
26400 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
26410 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e  ment. ^The filen
26420 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
26430 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
26440 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
26450 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
26460 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
26470 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
26480 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
26490 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
264a0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
264b0 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63   ^(A [database c
264c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
264d0 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
264e0 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
264f0 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
26500 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
26510 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
26520 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
26530 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
26540 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
26550 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
26560 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
26570 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
26580 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
26590 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
265a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
265b0 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
265c0 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65  ject.)^ ^(If the
265d0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
265e0 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
265f0 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
26600 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
26610 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
26620 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
26630 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
26640 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54  s returned.)^ ^T
26650 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
26660 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
26670 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
26680 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
26690 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
266a0 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
266b0 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
266c0 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  on of the error 
266d0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
266e0 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ure of any.** of
266f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   the sqlite3_ope
26700 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  n() routines..**
26710 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
26720 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62   encoding will b
26730 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61  e UTF-8 for data
26740 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73  bases created us
26750 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  ing.** sqlite3_o
26760 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
26770 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68  _open_v2().  ^Th
26780 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
26790 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73  ng for databases
267a0 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e  .** created usin
267b0 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  g sqlite3_open16
267c0 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31  () will be UTF-1
267d0 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
267e0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a  byte order..**.*
267f0 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
26800 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
26810 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
26820 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
26830 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
26840 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
26850 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
26860 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
26870 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
26880 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
26890 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
268a0 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
268b0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
268c0 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
268d0 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
268e0 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
268f0 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
26900 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
26910 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
26920 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
26930 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
26940 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
26950 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
26960 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65  nnection.  ^(The
26970 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
26980 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   to.** sqlite3_o
26990 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b  pen_v2() can tak
269a0 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
269b0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
269c0 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
269d0 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
269e0 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
269f0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
26a00 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
26a10 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  LMUTEX], [SQLITE
26a20 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
26a30 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  E],.** [SQLITE_O
26a40 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
26a50 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ], and/or [SQLIT
26a60 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
26a70 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
26a80 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
26a90 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
26aa0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
26ab0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
26ac0 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
26ad0 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
26ae0 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
26af0 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
26b00 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
26b10 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
26b20 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
26b30 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
26b40 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
26b50 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
26b60 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
26b70 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
26b80 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
26b90 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
26ba0 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
26bb0 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
26bc0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
26bd0 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
26be0 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
26bf0 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
26c00 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
26c10 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
26c20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
26c30 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
26c40 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
26c50 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
26c60 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
26c70 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
26c80 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
26c90 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
26ca0 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
26cb0 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20  reated if.** it 
26cc0 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
26cd0 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
26ce0 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
26cf0 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
26d00 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
26d10 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
26d20 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
26d30 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  >)^.** </dl>.**.
26d40 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
26d50 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
26d60 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
26d70 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
26d80 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
26d90 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f  hown above optio
26da0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
26db0 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51  ith other.** [SQ
26dc0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
26dd0 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e  LY | SQLITE_OPEN
26de0 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e  _* bits].** then
26df0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
26e00 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
26e10 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
26e20 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
26e30 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65  flag is set, the
26e40 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
26e50 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65  onnection.** ope
26e60 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d  ns in the multi-
26e70 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
26e80 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20  g mode] as long 
26e90 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68  as the single-th
26ea0 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73  read.** mode has
26eb0 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74   not been set at
26ec0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
26ed0 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49   start-time.  ^I
26ee0 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
26ef0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
26f00 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
26f10 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
26f20 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
26f30 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
26f40 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
26f50 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
26f60 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
26f70 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
26f80 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
26f90 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
26fa0 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ime..** ^The [SQ
26fb0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
26fc0 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
26fd0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
26fe0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65  connection to be
26ff0 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20  .** eligible to 
27000 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68  use [shared cach
27010 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c  e mode], regardl
27020 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
27030 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20  r not shared.** 
27040 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
27050 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
27060 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
27070 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a  che()].  ^The.**
27080 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
27090 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
270a0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
270b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
270c0 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63  to not.** partic
270d0 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64  ipate in [shared
270e0 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65   cache mode] eve
270f0 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c  n if it is enabl
27100 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
27110 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
27120 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
27130 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
27140 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
27150 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
27160 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
27170 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
27180 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
27190 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
271a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
271b0 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66  should use.  ^If
271c0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
271d0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
271e0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
271f0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
27200 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
27210 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
27220 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
27230 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
27240 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
27250 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
27260 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
27270 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
27280 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
27290 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
272a0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
272b0 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
272c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
272d0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
272e0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
272f0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
27300 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
27310 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
27320 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
27330 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
27340 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
27350 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
27360 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
27370 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
27380 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
27390 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
273a0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
273b0 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
273c0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
273d0 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
273e0 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
273f0 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
27400 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
27410 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
27420 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
27430 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
27440 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
27450 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
27460 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
27470 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
27480 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
27490 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
274a0 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
274b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
274c0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
274d0 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  d..**.** [[URI f
274e0 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69  ilenames in sqli
274f0 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33  te3_open()]] <h3
27500 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f  >URI Filenames</
27510 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55  h3>.**.** ^If [U
27520 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74  RI filename] int
27530 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
27540 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20  nabled, and the 
27550 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
27560 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68  t.** begins with
27570 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74   "file:", then t
27580 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69  he filename is i
27590 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
275a0 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c  URI. ^URI.** fil
275b0 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
275c0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20  tion is enabled 
275d0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
275e0 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
275f0 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 74  .** set in the t
27600 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
27610 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
27620 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73  (), or if it has
27630 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64  .** been enabled
27640 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20   globally using 
27650 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
27660 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77  IG_URI] option w
27670 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ith the.** [sqli
27680 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65  te3_config()] me
27690 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b  thod or by the [
276a0 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
276b0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
276c0 69 6f 6e 2e 0a 2a 2a 20 55 52 49 20 66 69 6c 65  ion..** URI file
276d0 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
276e0 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66  ion is turned of
276f0 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c  f.** by default,
27700 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65   but future rele
27710 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ases of SQLite m
27720 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20  ight enable URI 
27730 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65  filename.** inte
27740 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65  rpretation by de
27750 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52  fault.  See "[UR
27760 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f  I filenames]" fo
27770 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
27780 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
27790 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  ** URI filenames
277a0 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f   are parsed acco
277b0 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38  rding to RFC 398
277c0 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63  6. ^If the URI c
277d0 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75  ontains an.** au
277e0 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74  thority, then it
277f0 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
27800 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
27810 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a  or the string .*
27820 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e  * "localhost". ^
27830 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  If the authority
27840 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79   is not an empty
27850 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61   string or "loca
27860 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65  lhost", an .** e
27870 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
27880 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20   to the caller. 
27890 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f  ^The fragment co
278a0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
278b0 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74  , if .** present
278c0 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  , is ignored..**
278d0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
278e0 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e   the path compon
278f0 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61  ent of the URI a
27900 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
27910 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77  e disk file.** w
27920 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68  hich contains th
27930 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20  e database. ^If 
27940 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20  the path begins 
27950 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61  with a '/' chara
27960 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69  cter, .** then i
27970 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
27980 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   as an absolute 
27990 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61  path. ^If the pa
279a0 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69  th does not begi
279b0 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27  n .** with a '/'
279c0 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74   (meaning that t
279d0 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63  he authority sec
279e0 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20  tion is omitted 
279f0 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a  from the URI).**
27a00 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69   then the path i
27a10 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
27a20 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68   a relative path
27a30 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f  . .** ^(On windo
27a40 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f  ws, the first co
27a50 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62  mponent of an ab
27a60 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20  solute path .** 
27a70 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69  is a drive speci
27a80 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22  fication (e.g. "
27a90 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  C:").)^.**.** [[
27aa0 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70  core URI query p
27ab0 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54  arameters]].** T
27ac0 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
27ad0 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20  nt of a URI may 
27ae0 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65  contain paramete
27af0 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  rs that are inte
27b00 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65  rpreted.** eithe
27b10 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65  r by SQLite itse
27b20 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53  lf, or by a [VFS
27b30 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d   | custom VFS im
27b40 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a  plementation]..*
27b50 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73  * SQLite and its
27b60 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73   built-in [VFSes
27b70 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a  ] interpret the.
27b80 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65  ** following que
27b90 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a  ry parameters:.*
27ba0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  *.** <ul>.**   <
27bb0 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20  li> <b>vfs</b>: 
27bc0 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d  ^The "vfs" param
27bd0 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64  eter may be used
27be0 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
27bf0 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61  name of.**     a
27c00 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74   VFS object that
27c10 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70   provides the op
27c20 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
27c30 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68  nterface that sh
27c40 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75  ould.**     be u
27c50 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68  sed to access th
27c60 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
27c70 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69  on disk. ^If thi
27c80 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  s option is set 
27c90 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70  to.**     an emp
27ca0 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65  ty string the de
27cb0 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74  fault VFS object
27cc0 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69   is used. ^Speci
27cd0 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
27ce0 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61  .**     VFS is a
27cf0 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c  n error. ^If sql
27d00 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
27d10 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76  s used and the v
27d20 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  fs option is.** 
27d30 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65      present, the
27d40 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66  n the VFS specif
27d50 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f  ied by the optio
27d60 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e  n takes preceden
27d70 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74  ce over.**     t
27d80 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
27d90 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  as the fourth pa
27da0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
27db0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
27dc0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f  .**   <li> <b>mo
27dd0 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f  de</b>: ^(The mo
27de0 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  de parameter may
27df0 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
27e00 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a  r "ro", "rw",.**
27e10 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22       "rwc", or "
27e20 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74  memory". Attempt
27e30 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f  ing to set it to
27e40 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65   any other value
27e50 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72   is.**     an er
27e60 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e  ror)^. .**     ^
27e70 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69  If "ro" is speci
27e80 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64  fied, then the d
27e90 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
27ea0 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  d for read-only 
27eb0 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
27ec0 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b  just as if the [
27ed0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
27ee0 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62  ONLY] flag had b
27ef0 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a  een set in the .
27f00 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67  **     third arg
27f10 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
27f20 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20  _open_v2(). ^If 
27f30 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
27f40 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20  is set to .**   
27f50 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65    "rw", then the
27f60 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
27f70 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69  ned for read-wri
27f80 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61  te (but not crea
27f90 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  te) .**     acce
27fa0 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45  ss, as if SQLITE
27fb0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
27fc0 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f  (but not SQLITE_
27fd0 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64  OPEN_CREATE) had
27fe0 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65   .**     been se
27ff0 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20  t. ^Value "rwc" 
28000 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
28010 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a   setting both .*
28020 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
28030 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20  N_READWRITE and 
28040 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
28050 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64  TE.  ^If the mod
28060 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  e option is.**  
28070 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72     set to "memor
28080 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b  y" then a pure [
28090 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
280a0 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72  se] that never r
280b0 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77  eads.**     or w
280c0 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20  rites from disk 
280d0 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20  is used. ^It is 
280e0 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63  an error to spec
280f0 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a  ify a value for.
28100 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20  **     the mode 
28110 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69  parameter that i
28120 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69  s less restricti
28130 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65  ve than that spe
28140 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
28150 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65   the flags passe
28160 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70  d in the third p
28170 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
28180 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
28190 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63  *.**   <li> <b>c
281a0 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63  ache</b>: ^The c
281b0 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d  ache parameter m
281c0 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
281d0 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a  her "shared" or.
281e0 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22  **     "private"
281f0 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f  . ^Setting it to
28200 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75   "shared" is equ
28210 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
28220 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51  ng the.**     SQ
28230 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
28240 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65  CACHE bit in the
28250 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
28260 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20  passed to.**    
28270 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
28280 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65  (). ^Setting the
28290 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
282a0 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73   to "private" is
282b0 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c   .**     equival
282c0 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
282d0 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  he SQLITE_OPEN_P
282e0 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e  RIVATECACHE bit.
282f0 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69  .**     ^If sqli
28300 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
28310 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63   used and the "c
28320 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20  ache" parameter 
28330 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a  is present in.**
28340 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e       a URI filen
28350 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f  ame, its value o
28360 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68  verrides any beh
28370 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20  avior requested 
28380 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20  by setting.**   
28390 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52    SQLITE_OPEN_PR
283a0 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51  IVATECACHE or SQ
283b0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
283c0 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a  CACHE flag..**.*
283d0 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c  *  <li> <b>psow<
283e0 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70  /b>: ^The psow p
283f0 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74  arameter indicat
28400 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  es whether or no
28410 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f  t the.**     [po
28420 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74  wersafe overwrit
28430 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73  e] property does
28440 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70   or does not app
28450 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  ly to the.**    
28460 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f   storage media o
28470 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61  n which the data
28480 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65  base file reside
28490 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  s..**.**  <li> <
284a0 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54  b>nolock</b>: ^T
284b0 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65  he nolock parame
284c0 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  ter is a boolean
284d0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
284e0 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66  .**     which if
284f0 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69   set disables fi
28500 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f  le locking in ro
28510 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d  llback journal m
28520 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20  odes.  This.**  
28530 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72     is useful for
28540 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74   accessing a dat
28550 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73  abase on a files
28560 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20  ystem that does 
28570 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f  not.**     suppo
28580 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75  rt locking.  Cau
28590 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20  tion:  Database 
285a0 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74  corruption might
285b0 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a   result if two.*
285c0 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72  *     or more pr
285d0 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f  ocesses write to
285e0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
285f0 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f  se and any one o
28600 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70  f those.**     p
28610 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f  rocesses uses no
28620 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c  lock=1..**.**  <
28630 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65  li> <b>immutable
28640 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74  </b>: ^The immut
28650 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69  able parameter i
28660 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72  s a boolean quer
28670 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74  y.**     paramet
28680 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  er that indicate
28690 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
286a0 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72  ase file is stor
286b0 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61  ed on.**     rea
286c0 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e  d-only media.  ^
286d0 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69  When immutable i
286e0 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73  s set, SQLite as
286f0 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
28700 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66  *     database f
28710 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  ile cannot be ch
28720 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61  anged, even by a
28730 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69   process with hi
28740 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76  gher.**     priv
28750 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68  ilege, and so th
28760 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
28770 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61  ened read-only a
28780 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a  nd all locking.*
28790 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65  *     and change
287a0 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69   detection is di
287b0 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e  sabled.  Caution
287c0 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d  : Setting the im
287d0 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70  mutable.**     p
287e0 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74  roperty on a dat
287f0 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20  abase file that 
28800 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61  does in fact cha
28810 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a  nge can result.*
28820 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65  *     in incorre
28830 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  ct query results
28840 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
28850 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e  CORRUPT] errors.
28860 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f  .**     See also
28870 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  : [SQLITE_IOCAP_
28880 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20  IMMUTABLE]..**  
28890 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a       .** </ul>.*
288a0 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67  *.** ^Specifying
288b0 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61   an unknown para
288c0 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65  meter in the que
288d0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
288e0 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a  a URI is not an.
288f0 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72  ** error.  Futur
28900 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
28910 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72  Lite might under
28920 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c  stand additional
28930 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
28940 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65  ters.  See "[que
28950 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69  ry parameters wi
28960 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69  th special meani
28970 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66  ng to SQLite]" f
28980 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  or.** additional
28990 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
289a0 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
289b0 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68  me examples]] <h
289c0 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  3>URI filename e
289d0 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  xamples</h3>.**.
289e0 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
289f0 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65  ="1" align=cente
28a00 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e  r cellpadding=5>
28a10 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49  .** <tr><th> URI
28a20 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20   filenames <th> 
28a30 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c  Results.** <tr><
28a40 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
28a50 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
28a60 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65     Open the file
28a70 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
28a80 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
28a90 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ory..** <tr><td>
28aa0 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
28ab0 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20  /data.db<br>.** 
28ac0 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
28ad0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
28ae0 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20  db <br> .**     
28af0 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61       file://loca
28b00 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f  lhost/home/fred/
28b10 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64  data.db <br> <td
28b20 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
28b30 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
28b40 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
28b50 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c  d/data.db"..** <
28b60 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64  tr><td> file://d
28b70 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65  arkstar/home/fre
28b80 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  d/data.db <td> .
28b90 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
28ba0 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22  rror. "darkstar"
28bb0 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e   is not a recogn
28bc0 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a  ized authority..
28bd0 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65  ** <tr><td style
28be0 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f  ="white-space:no
28bf0 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20  wrap"> .**      
28c00 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44      file:///C:/D
28c10 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32  ocuments%20and%2
28c20 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44  0Settings/fred/D
28c30 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a  esktop/data.db.*
28c40 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f  *     <td> Windo
28c50 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68  ws only: Open th
28c60 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
28c70 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74   on fred's deskt
28c80 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20  op on drive.**  
28c90 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65          C:. Note
28ca0 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73   that the %20 es
28cb0 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65  caping in this e
28cc0 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74  xample is not st
28cd0 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20  rictly .**      
28ce0 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20      necessary - 
28cf0 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73  space characters
28d00 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74   can be used lit
28d10 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20  erally.**       
28d20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61     in URI filena
28d30 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  mes..** <tr><td>
28d40 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
28d50 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76  de=ro&cache=priv
28d60 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  ate <td> .**    
28d70 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
28d80 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
28d90 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
28da0 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ry for read-only
28db0 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20   access..**     
28dc0 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20       Regardless 
28dd0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
28de0 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d  t shared-cache m
28df0 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62  ode is enabled b
28e00 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65  y.**          de
28e10 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69  fault, use a pri
28e20 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c  vate cache..** <
28e30 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
28e40 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f  me/fred/data.db?
28e50 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65  vfs=unix-dotfile
28e60 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20   <td>.**        
28e70 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f    Open file "/ho
28e80 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
28e90 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61  . Use the specia
28ea0 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66  l VFS "unix-dotf
28eb0 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20  ile".**         
28ec0 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66   that uses dot-f
28ed0 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66  iles in place of
28ee0 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20   posix advisory 
28ef0 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e  locking..** <tr>
28f00 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
28f10 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20  b?mode=readonly 
28f20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
28f30 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61    An error. "rea
28f40 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20  donly" is not a 
28f50 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72  valid option for
28f60 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61   the "mode" para
28f70 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c  meter..** </tabl
28f80 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65  e>.**.** ^URI he
28f90 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
28fa0 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29   sequences (%HH)
28fb0 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77   are supported w
28fc0 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61  ithin the path a
28fd0 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70  nd.** query comp
28fe0 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e  onents of a URI.
28ff0 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65   A hexadecimal e
29000 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63  scape sequence c
29010 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20  onsists of a.** 
29020 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22  percent sign - "
29030 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79  %" - followed by
29040 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78   exactly two hex
29050 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20  adecimal digits 
29060 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61  .** specifying a
29070 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e  n octet value. ^
29080 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20  Before the path 
29090 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  or query compone
290a0 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20  nts of a.** URI 
290b0 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74  filename are int
290c0 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61  erpreted, they a
290d0 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  re encoded using
290e0 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a   UTF-8 and all .
290f0 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  ** hexadecimal e
29100 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
29110 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69  replaced by a si
29120 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69  ngle byte contai
29130 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72  ning the.** corr
29140 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e  esponding octet.
29150 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73   If this process
29160 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e   generates an in
29170 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f  valid UTF-8 enco
29180 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73  ding,.** the res
29190 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
291a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
291b0 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
291c0 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
291d0 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
291e0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
291f0 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
29200 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
29210 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
29220 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
29230 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
29240 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
29250 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
29260 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
29270 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
29280 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
29290 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
292a0 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
292b0 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
292c0 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
292d0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
292e0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
292f0 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
29300 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75  indows Runtime u
29310 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74  sers:</b>  The t
29320 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f  emporary directo
29330 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a  ry must be set.*
29340 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  * prior to calli
29350 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ng sqlite3_open(
29360 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
29370 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69  n_v2().  Otherwi
29380 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66  se, various.** f
29390 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71  eatures that req
293a0 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20  uire the use of 
293b0 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20  temporary files 
293c0 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20  may fail..**.** 
293d0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
293e0 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
293f0 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  y].*/.int sqlite
29400 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
29410 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
29420 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
29430 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
29440 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
29450 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
29460 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
29470 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
29480 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
29490 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
294a0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
294b0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
294c0 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
294d0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
294e0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
294f0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
29500 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
29510 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
29520 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
29530 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
29540 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
29550 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
29560 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
29570 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
29580 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
29590 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
295a0 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
295b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
295c0 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
295d0 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
295e0 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
295f0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
29600 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52  in Values For UR
29610 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  I Parameters.**.
29620 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69  ** These are uti
29630 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75  lity routines, u
29640 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70  seful to VFS imp
29650 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68  lementations, th
29660 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73  at check.** to s
29670 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65  ee if a database
29680 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20   file was a URI 
29690 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61  that contained a
296a0 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20   specific query 
296b0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61  .** parameter, a
296c0 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73  nd if so obtains
296d0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
296e0 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  at query paramet
296f0 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69  er..**.** If F i
29700 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
29710 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  ilename pointer 
29720 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
29730 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f  xOpen() method o
29740 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c  f .** a VFS impl
29750 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20  ementation when 
29760 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  the flags parame
29770 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68  ter to xOpen() h
29780 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f  as one or .** mo
29790 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  re of the [SQLIT
297a0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b  E_OPEN_URI] or [
297b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
297c0 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e  _DB] bits set an
297d0 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61  d.** P is the na
297e0 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  me of the query 
297f0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a  parameter, then.
29800 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  ** sqlite3_uri_p
29810 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
29820 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20  turns the value 
29830 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61  of the P.** para
29840 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73  meter if it exis
29850 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ts or a NULL poi
29860 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e  nter if P does n
29870 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a  ot appear as a .
29880 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ** query paramet
29890 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69  er on F.  If P i
298a0 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65  s a query parame
298b0 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20  ter of F.** has 
298c0 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75  no explicit valu
298d0 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
298e0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
298f0 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  P) returns.** a 
29900 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d  pointer to an em
29910 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  pty string..**.*
29920 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72  * The sqlite3_ur
29930 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
29940 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73   routine assumes
29950 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f   that P is a boo
29960 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65  lean.** paramete
29970 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72  r and returns tr
29980 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20  ue (1) or false 
29990 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  (0) according to
299a0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66   the value.** of
299b0 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33   P.  The sqlite3
299c0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
299d0 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,B) routine retu
299e0 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20  rns true (1) if 
299f0 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
29a00 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
29a10 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73  P is one of "yes
29a20 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f  ", "true", or "o
29a30 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73  n" in any.** cas
29a40 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  e or if the valu
29a50 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  e begins with a 
29a60 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e  non-zero number.
29a70 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65    The .** sqlite
29a80 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
29a90 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65  P,B) routines re
29aa0 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20  turns false (0) 
29ab0 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a  if the value of.
29ac0 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ** query paramet
29ad0 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22  er P is one of "
29ae0 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72  no", "false", or
29af0 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61   "off" in any ca
29b00 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20  se or.** if the 
29b10 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
29b20 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f  h a numeric zero
29b30 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61  .  If P is not a
29b40 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
29b50 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74  ter on F or if t
29b60 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
29b70 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20   does not match 
29b80 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62  any of the.** ab
29b90 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ove, then sqlite
29ba0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
29bb0 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21  P,B) returns (B!
29bc0 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  =0)..**.** The s
29bd0 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
29be0 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20  (F,P,D) routine 
29bf0 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c  converts the val
29c00 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a  ue of P into a.*
29c10 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  * 64-bit signed 
29c20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75  integer and retu
29c30 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72  rns that integer
29c40 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73  , or D if P does
29c50 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20   not.** exist.  
29c60 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  If the value of 
29c70 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f  P is something o
29c80 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74  ther than an int
29c90 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65  eger, then.** ze
29ca0 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
29cb0 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61  ** .** If F is a
29cc0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
29cd0 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
29ce0 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
29cf0 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a  eturns NULL and.
29d00 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
29d10 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
29d20 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69  turns B.  If F i
29d30 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69  s not a NULL poi
29d40 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e  nter and.** is n
29d50 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
29d60 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e  le pathname poin
29d70 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  ter that SQLite 
29d80 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
29d90 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74  xOpen.** VFS met
29da0 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65  hod, then the be
29db0 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72  havior of this r
29dc0 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69  outine is undefi
29dd0 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
29de0 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  .** undesirable.
29df0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
29e00 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
29e10 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72  meter(const char
29e20 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e   *zFilename, con
29e30 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29  st char *zParam)
29e40 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72  ;.int sqlite3_ur
29e50 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20  i_boolean(const 
29e60 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e  char *zFile, con
29e70 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c  st char *zParam,
29e80 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a   int bDefault);.
29e90 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
29ea0 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
29eb0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e  const char*, con
29ec0 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
29ed0 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a  3_int64);.../*.*
29ee0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
29ef0 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
29f00 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ages.** METHOD: 
29f10 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49  sqlite3.**.** ^I
29f20 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
29f30 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20  t sqlite3_* API 
29f40 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20  call associated 
29f50 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61  with .** [databa
29f60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
29f70 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68   failed, then th
29f80 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
29f90 65 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  e(D) interface.*
29fa0 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  * returns the nu
29fb0 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
29fc0 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  de] or [extended
29fd0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f   result code] fo
29fe0 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61  r that.** API ca
29ff0 6c 6c 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ll..** ^The sqli
2a000 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
2a010 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
2a020 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
2a030 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
2a040 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
2a050 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
2a060 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
2a070 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
2a080 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
2a090 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
2a0a0 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 73 20 72  .** The values r
2a0b0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2a0c0 65 33 5f 65 72 72 63 6f 64 65 28 29 20 61 6e 64  e3_errcode() and
2a0d0 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  /or.** sqlite3_e
2a0e0 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
2a0f0 29 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 77  ) might change w
2a100 69 74 68 20 65 61 63 68 20 41 50 49 20 63 61 6c  ith each API cal
2a110 6c 2e 0a 2a 2a 20 45 78 63 65 70 74 2c 20 74 68  l..** Except, th
2a120 65 72 65 20 61 72 65 20 73 6f 6d 65 20 69 6e 74  ere are some int
2a130 65 72 66 61 63 65 73 20 74 68 61 74 20 61 72 65  erfaces that are
2a140 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 6e   guaranteed to n
2a150 65 76 65 72 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ever.** change t
2a160 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2a170 65 72 72 6f 72 20 63 6f 64 65 2e 20 20 54 68 65  error code.  The
2a180 20 65 72 72 6f 72 2d 63 6f 64 65 20 70 72 65 73   error-code pres
2a190 65 72 76 69 6e 67 0a 2a 2a 20 69 6e 74 65 72 66  erving.** interf
2a1a0 61 63 65 73 20 61 72 65 3a 0a 2a 2a 0a 2a 2a 20  aces are:.**.** 
2a1b0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c  <ul>.** <li> sql
2a1c0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 0a 2a  ite3_errcode().*
2a1d0 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65  * <li> sqlite3_e
2a1e0 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
2a1f0 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65  ).** <li> sqlite
2a200 33 5f 65 72 72 6d 73 67 28 29 0a 2a 2a 20 3c 6c  3_errmsg().** <l
2a210 69 3e 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  i> sqlite3_errms
2a220 67 31 36 28 29 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  g16().** </ul>.*
2a230 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2a240 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73  3_errmsg() and s
2a250 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
2a260 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  ) return English
2a270 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78  -language.** tex
2a280 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  t that describes
2a290 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65   the error, as e
2a2a0 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
2a2b0 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65  TF-16 respective
2a2c0 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20  ly..** ^(Memory 
2a2d0 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
2a2e0 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
2a2f0 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
2a300 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61  rnally..** The a
2a310 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20  pplication does 
2a320 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72  not need to worr
2a330 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20  y about freeing 
2a340 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48  the result..** H
2a350 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f  owever, the erro
2a360 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62  r string might b
2a370 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
2a380 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a   deallocated by.
2a390 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ** subsequent ca
2a3a0 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c  lls to other SQL
2a3b0 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75  ite interface fu
2a3c0 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a  nctions.)^.**.**
2a3d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
2a3e0 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65  rstr() interface
2a3f0 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67   returns the Eng
2a400 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65  lish-language te
2a410 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72  xt.** that descr
2a420 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74  ibes the [result
2a430 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38   code], as UTF-8
2a440 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
2a450 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
2a460 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
2a470 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
2a480 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74  ally.** and must
2a490 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79   not be freed by
2a4a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2a4b0 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  )^..**.** When t
2a4c0 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
2a4d0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
2a4e0 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67  s in use, it mig
2a4f0 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73  ht be the.** cas
2a500 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20  e that a second 
2a510 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20  error occurs on 
2a520 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
2a530 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  d in between.** 
2a540 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20  the time of the 
2a550 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20  first error and 
2a560 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73  the call to thes
2a570 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  e interfaces..**
2a580 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65   When that happe
2a590 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ns, the second e
2a5a0 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70  rror will be rep
2a5b0 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73  orted since thes
2a5c0 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
2a5d0 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68  always report th
2a5e0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65  e most recent re
2a5f0 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a  sult.  To avoid.
2a600 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68  ** this, each th
2a610 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20  read can obtain 
2a620 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66  exclusive use of
2a630 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2a640 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
2a650 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  by invoking [sql
2a660 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
2a670 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
2a680 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20  tex](D)) before 
2a690 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20  beginning.** to 
2a6a0 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69  use D and invoki
2a6b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
2a6c0 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65  x_leave]([sqlite
2a6d0 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
2a6e0 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c  after.** all cal
2a6f0 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66  ls to the interf
2a700 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65  aces listed here
2a710 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a   are completed..
2a720 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
2a730 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
2a740 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
2a750 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
2a760 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
2a770 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
2a780 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
2a790 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
2a7a0 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
2a7b0 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
2a7c0 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
2a7d0 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69  not be set..*/.i
2a7e0 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
2a7f0 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
2a800 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
2a810 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
2a820 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73  lite3 *db);.cons
2a830 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2a840 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
2a850 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2a860 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
2a870 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
2a880 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
2a890 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  rstr(int);../*.*
2a8a0 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 70  * CAPI3REF: Prep
2a8b0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2a8c0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
2a8d0 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
2a8e0 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
2a8f0 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
2a900 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
2a910 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
2a920 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
2a930 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
2a940 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65   that.** has bee
2a950 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  n compiled into 
2a960 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20  binary form and 
2a970 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 20 65  is ready to be e
2a980 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  valuated..**.** 
2a990 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51  Think of each SQ
2a9a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61  L statement as a
2a9b0 20 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74   separate comput
2a9c0 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65  er program.  The
2a9d0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
2a9e0 20 74 65 78 74 20 69 73 20 73 6f 75 72 63 65 20   text is source 
2a9f0 63 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72 65  code.  A prepare
2aa00 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
2aa10 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f  ct .** is the co
2aa20 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f  mpiled object co
2aa30 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73  de.  All SQL mus
2aa40 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69  t be converted i
2aa50 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65  nto a.** prepare
2aa60 64 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f  d statement befo
2aa70 72 65 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e  re it can be run
2aa80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65  ..**.** The life
2aa90 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70  -cycle of a prep
2aaa0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
2aab0 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f  bject usually go
2aac0 65 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  es like this:.**
2aad0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
2aae0 20 43 72 65 61 74 65 20 74 68 65 20 70 72 65 70   Create the prep
2aaf0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
2ab00 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
2ab10 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2ab20 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  )]..** <li> Bind
2ab30 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61   values to [para
2ab40 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
2ab50 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2ab60 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
2ab70 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
2ab80 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
2ab90 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
2aba0 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
2abb0 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
2abc0 3e 20 52 65 73 65 74 20 74 68 65 20 70 72 65 70  > Reset the prep
2abd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
2abe0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
2abf0 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
2ac00 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
2ac10 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
2ac20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
2ac30 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
2ac40 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
2ac50 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
2ac60 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
2ac70 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ol>.*/.typedef s
2ac80 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74  truct sqlite3_st
2ac90 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b  mt sqlite3_stmt;
2aca0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2acb0 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74  : Run-time Limit
2acc0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
2acd0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ite3.**.** ^(Thi
2ace0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
2acf0 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76  ws the size of v
2ad00 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74  arious construct
2ad10 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a  s to be limited.
2ad20 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69  ** on a connecti
2ad30 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e  on by connection
2ad40 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72   basis.  The fir
2ad50 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2ad60 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
2ad70 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f   connection] who
2ad80 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62  se limit is to b
2ad90 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64  e set or queried
2ada0 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
2adb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
2adc0 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20  e of the [limit 
2add0 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74  categories] that
2ade0 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61   define a.** cla
2adf0 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73  ss of constructs
2ae00 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69   to be size limi
2ae10 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20  ted.  The third 
2ae20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2ae30 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f  .** new limit fo
2ae40 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74  r that construct
2ae50 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  .)^.**.** ^If th
2ae60 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61  e new limit is a
2ae70 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
2ae80 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75  , the limit is u
2ae90 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46  nchanged..** ^(F
2aea0 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61  or each limit ca
2aeb0 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49  tegory SQLITE_LI
2aec0 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20  MIT_<i>NAME</i> 
2aed0 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b  there is a .** [
2aee0 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70  limits | hard up
2aef0 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65  per bound].** se
2af00 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
2af10 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63  e by a C preproc
2af20 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c  essor macro call
2af30 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  ed.** [limits | 
2af40 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41  SQLITE_MAX_<i>NA
2af50 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65  ME</i>]..** (The
2af60 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68   "_LIMIT_" in th
2af70 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65  e name is change
2af80 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e  d to "_MAX_".))^
2af90 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f  .** ^Attempts to
2afa0 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69   increase a limi
2afb0 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64  t above its hard
2afc0 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65   upper bound are
2afd0 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75  .** silently tru
2afe0 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61  ncated to the ha
2aff0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a  rd upper bound..
2b000 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73  **.** ^Regardles
2b010 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
2b020 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61  not the limit wa
2b030 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a  s changed, the .
2b040 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ** [sqlite3_limi
2b050 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  t()] interface r
2b060 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72  eturns the prior
2b070 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69   value of the li
2b080 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20  mit..** ^Hence, 
2b090 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72  to find the curr
2b0a0 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c  ent value of a l
2b0b0 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61  imit without cha
2b0c0 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d  nging it,.** sim
2b0d0 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20  ply invoke this 
2b0e0 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74  interface with t
2b0f0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2b100 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a  er set to -1..**
2b110 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d  .** Run-time lim
2b120 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  its are intended
2b130 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c   for use in appl
2b140 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61  ications that ma
2b150 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65  nage.** both the
2b160 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20  ir own internal 
2b170 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73  database and als
2b180 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74  o databases that
2b190 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a   are controlled.
2b1a0 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20  ** by untrusted 
2b1b0 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
2b1c0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70  .  An example ap
2b1d0 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20  plication might 
2b1e0 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77  be a.** web brow
2b1f0 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73  ser that has its
2b200 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66   own databases f
2b210 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f  or storing histo
2b220 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61  ry and.** separa
2b230 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e  te databases con
2b240 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53  trolled by JavaS
2b250 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f  cript applicatio
2b260 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a  ns downloaded.**
2b270 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65   off the Interne
2b280 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c  t.  The internal
2b290 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62   databases can b
2b2a0 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c  e given the.** l
2b2b0 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69  arge, default li
2b2c0 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73  mits.  Databases
2b2d0 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65   managed by exte
2b2e0 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e  rnal sources can
2b2f0 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63  .** be given muc
2b300 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73  h smaller limits
2b310 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65   designed to pre
2b320 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66  vent a denial of
2b330 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61   service.** atta
2b340 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20  ck.  Developers 
2b350 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20  might also want 
2b360 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69  to use the [sqli
2b370 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
2b380 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  er()].** interfa
2b390 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f  ce to further co
2b3a0 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20  ntrol untrusted 
2b3b0 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  SQL.  The size o
2b3c0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
2b3d0 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20  * created by an 
2b3e0 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74  untrusted script
2b3f0 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65   can be containe
2b400 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  d using the.** [
2b410 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
2b420 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20  [PRAGMA]..**.** 
2b430 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d  New run-time lim
2b440 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61  it categories ma
2b450 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
2b460 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
2b470 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  /.int sqlite3_li
2b480 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  mit(sqlite3*, in
2b490 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c  t id, int newVal
2b4a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b4b0 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d  EF: Run-Time Lim
2b4c0 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a  it Categories.**
2b4d0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69   KEYWORDS: {limi
2b4e0 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69  t category} {*li
2b4f0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a  mit categories}.
2b500 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
2b510 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72  tants define var
2b520 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65  ious performance
2b530 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20   limits.** that 
2b540 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61  can be lowered a
2b550 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67  t run-time using
2b560 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
2b570 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70  )]..** The synop
2b580 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69  sis of the meani
2b590 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f  ngs of the vario
2b5a0 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f  us limits is sho
2b5b0 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64  wn below..** Add
2b5c0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
2b5d0 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ion is available
2b5e0 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69   at [limits | Li
2b5f0 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e  mits in SQLite].
2b600 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
2b610 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
2b620 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
2b630 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
2b640 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2b650 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
2b660 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42   any string or B
2b670 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77  LOB or table row
2b680 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29  , in bytes.<dd>)
2b690 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2b6a0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
2b6b0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
2b6c0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
2b6d0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
2b6e0 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
2b6f0 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
2b700 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c  ment, in bytes.<
2b710 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2b720 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
2b730 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  MN]] ^(<dt>SQLIT
2b740 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f  E_LIMIT_COLUMN</
2b750 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2b760 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2b770 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   columns in a ta
2b780 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  ble definition o
2b790 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75  r in the.** resu
2b7a0 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
2b7b0 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69  ECT] or the maxi
2b7c0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
2b7d0 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65  lumns in an inde
2b7e0 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52  x.** or in an OR
2b7f0 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20  DER BY or GROUP 
2b800 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29  BY clause.</dd>)
2b810 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2b820 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
2b830 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
2b840 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
2b850 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
2b860 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
2b870 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65  of the parse tre
2b880 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73  e on any express
2b890 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
2b8a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2b8b0 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
2b8c0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2b8d0 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
2b8e0 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ELECT</dt>.** <d
2b8f0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
2b900 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
2b910 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45   a compound SELE
2b920 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  CT statement.</d
2b930 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2b940 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
2b950 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  P]] ^(<dt>SQLITE
2b960 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
2b970 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2b980 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2b990 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
2b9a0 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
2b9b0 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
2b9c0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
2b9d0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
2b9e0 2e 20 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 70  .  If [sqlite3_p
2b9f0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a  repare_v2()] or.
2ba00 2a 2a 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  ** the equivalen
2ba10 74 20 74 72 69 65 73 20 74 6f 20 61 6c 6c 6f 63  t tries to alloc
2ba20 61 74 65 20 73 70 61 63 65 20 66 6f 72 20 6d 6f  ate space for mo
2ba30 72 65 20 74 68 61 6e 20 74 68 69 73 20 6d 61 6e  re than this man
2ba40 79 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 69 6e 20  y opcodes.** in 
2ba50 61 20 73 69 6e 67 6c 65 20 70 72 65 70 61 72 65  a single prepare
2ba60 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 61 6e 20  d statement, an 
2ba70 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65 72 72  SQLITE_NOMEM err
2ba80 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
2ba90 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2baa0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
2bab0 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74  TION_ARG]] ^(<dt
2bac0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
2bad0 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
2bae0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2baf0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
2bb00 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
2bb10 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tion.</dd>)^.**.
2bb20 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2bb30 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c  T_ATTACHED]] ^(<
2bb40 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2bb50 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
2bb60 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2bb70 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
2bb80 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
2bb90 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
2bba0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2bbb0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
2bbc0 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e  RN_LENGTH]].** ^
2bbd0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2bbe0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
2bbf0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
2bc00 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
2bc10 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
2bc20 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
2bc30 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
2bc40 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
2bc50 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
2bc60 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
2bc70 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d  ARIABLE_NUMBER]]
2bc80 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
2bc90 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
2bca0 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
2bcb0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
2bcc0 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
2bcd0 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
2bce0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
2bcf0 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  nt.)^.**.** [[SQ
2bd00 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
2bd10 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  ER_DEPTH]] ^(<dt
2bd20 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  >SQLITE_LIMIT_TR
2bd30 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e  IGGER_DEPTH</dt>
2bd40 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2bd50 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
2bd60 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
2bd70 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ers.</dd>)^.**.*
2bd80 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2bd90 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d  _WORKER_THREADS]
2bda0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2bdb0 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
2bdc0 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ADS</dt>.** <dd>
2bdd0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
2bde0 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20  er of auxiliary 
2bdf0 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74  worker threads t
2be00 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20  hat a single.** 
2be10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2be20 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c  ent] may start.<
2be30 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
2be40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2be50 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
2be60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2be70 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
2be80 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
2be90 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
2bea0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
2beb0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
2bec0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2bed0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2bee0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
2bef0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
2bf00 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
2bf10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
2bf20 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
2bf30 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
2bf40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
2bf50 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
2bf60 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
2bf70 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
2bf80 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
2bf90 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
2bfa0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
2bfb0 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
2bfc0 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
2bfd0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2bfe0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
2bff0 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
2c000 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2c010 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
2c020 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
2c030 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2c040 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20  T_TRIGGER_DEPTH 
2c050 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
2c060 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2c070 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
2c080 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a  S           11..
2c090 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c0a0 50 72 65 70 61 72 65 20 46 6c 61 67 73 0a 2a 2a  Prepare Flags.**
2c0b0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2c0c0 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
2c0d0 75 73 20 66 6c 61 67 73 20 74 68 61 74 20 63 61  us flags that ca
2c0e0 6e 20 62 65 20 70 61 73 73 65 64 20 69 6e 74 6f  n be passed into
2c0f0 0a 2a 2a 20 22 70 72 65 70 46 6c 61 67 73 22 20  .** "prepFlags" 
2c100 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
2c110 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c120 65 5f 76 33 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  e_v3()] and.** [
2c130 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2c140 36 5f 76 33 28 29 5d 20 69 6e 74 65 72 66 61 63  6_v3()] interfac
2c150 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 66 6c  es..**.** New fl
2c160 61 67 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ags may be added
2c170 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
2c180 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
2c190 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
2c1a0 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45  QLITE_PREPARE_PE
2c1b0 52 53 49 53 54 45 4e 54 5d 5d 20 5e 28 3c 64 74  RSISTENT]] ^(<dt
2c1c0 3e 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f  >SQLITE_PREPARE_
2c1d0 50 45 52 53 49 53 54 45 4e 54 3c 2f 64 74 3e 0a  PERSISTENT</dt>.
2c1e0 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54  ** <dd>The SQLIT
2c1f0 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53  E_PREPARE_PERSIS
2c200 54 45 4e 54 20 66 6c 61 67 20 69 73 20 61 20 68  TENT flag is a h
2c210 69 6e 74 20 74 6f 20 74 68 65 20 71 75 65 72 79  int to the query
2c220 20 70 6c 61 6e 6e 65 72 0a 2a 2a 20 74 68 61 74   planner.** that
2c230 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2c240 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
2c250 72 65 74 61 69 6e 65 64 20 66 6f 72 20 61 20 6c  retained for a l
2c260 6f 6e 67 20 74 69 6d 65 20 61 6e 64 0a 2a 2a 20  ong time and.** 
2c270 70 72 6f 62 61 62 6c 79 20 72 65 75 73 65 64 20  probably reused 
2c280 6d 61 6e 79 20 74 69 6d 65 73 2e 29 5e 20 5e 57  many times.)^ ^W
2c290 69 74 68 6f 75 74 20 74 68 69 73 20 66 6c 61 67  ithout this flag
2c2a0 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
2c2b0 72 65 5f 76 33 28 29 5d 0a 2a 2a 20 61 6e 64 20  re_v3()].** and 
2c2c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c2d0 31 36 5f 76 33 28 29 5d 20 61 73 73 75 6d 65 20  16_v3()] assume 
2c2e0 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65  that the prepare
2c2f0 64 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  d statement will
2c300 20 0a 2a 2a 20 62 65 20 75 73 65 64 20 6a 75 73   .** be used jus
2c310 74 20 6f 6e 63 65 20 6f 72 20 61 74 20 6d 6f 73  t once or at mos
2c320 74 20 61 20 66 65 77 20 74 69 6d 65 73 20 61 6e  t a few times an
2c330 64 20 74 68 65 6e 20 64 65 73 74 72 6f 79 65 64  d then destroyed
2c340 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2c350 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 72  e3_finalize()] r
2c360 65 6c 61 74 69 76 65 6c 79 20 73 6f 6f 6e 2e 20  elatively soon. 
2c370 54 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  The current impl
2c380 65 6d 65 6e 74 61 74 69 6f 6e 20 61 63 74 73 0a  ementation acts.
2c390 2a 2a 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20  ** on this hint 
2c3a0 62 79 20 61 76 6f 69 64 69 6e 67 20 74 68 65 20  by avoiding the 
2c3b0 75 73 65 20 6f 66 20 5b 6c 6f 6f 6b 61 73 69 64  use of [lookasid
2c3c0 65 20 6d 65 6d 6f 72 79 5d 20 73 6f 20 61 73 20  e memory] so as 
2c3d0 6e 6f 74 20 74 6f 0a 2a 2a 20 64 65 70 6c 65 74  not to.** deplet
2c3e0 65 20 74 68 65 20 6c 69 6d 69 74 65 64 20 73 74  e the limited st
2c3f0 6f 72 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65  ore of lookaside
2c400 20 6d 65 6d 6f 72 79 2e 20 46 75 74 75 72 65 20   memory. Future 
2c410 76 65 72 73 69 6f 6e 73 20 6f 66 0a 2a 2a 20 53  versions of.** S
2c420 51 4c 69 74 65 20 6d 61 79 20 61 63 74 20 6f 6e  QLite may act on
2c430 20 74 68 69 73 20 68 69 6e 74 20 64 69 66 66 65   this hint diffe
2c440 72 65 6e 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  rently..**.** [[
2c450 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e  SQLITE_PREPARE_N
2c460 4f 52 4d 41 4c 49 5a 45 5d 5d 20 5e 28 3c 64 74  ORMALIZE]] ^(<dt
2c470 3e 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f  >SQLITE_PREPARE_
2c480 4e 4f 52 4d 41 4c 49 5a 45 3c 2f 64 74 3e 0a 2a  NORMALIZE</dt>.*
2c490 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45  * <dd>The SQLITE
2c4a0 5f 50 52 45 50 41 52 45 5f 4e 4f 52 4d 41 4c 49  _PREPARE_NORMALI
2c4b0 5a 45 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65  ZE flag indicate
2c4c0 73 20 74 68 61 74 20 61 20 6e 6f 72 6d 61 6c 69  s that a normali
2c4d0 7a 65 64 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74  zed.** represent
2c4e0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
2c4f0 20 73 74 61 74 65 6d 65 6e 74 20 73 68 6f 75 6c   statement shoul
2c500 64 20 62 65 20 63 61 6c 63 75 6c 61 74 65 64 20  d be calculated 
2c510 61 6e 64 20 74 68 65 6e 0a 2a 2a 20 61 73 73 6f  and then.** asso
2c520 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2c530 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c540 6e 74 2c 20 77 68 69 63 68 20 63 61 6e 20 62 65  nt, which can be
2c550 20 6f 62 74 61 69 6e 65 64 20 76 69 61 0a 2a 2a   obtained via.**
2c560 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6e 6f   the [sqlite3_no
2c570 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 29 5d 20  rmalized_sql()] 
2c580 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
2c590 73 65 6d 61 6e 74 69 63 73 20 75 73 65 64 20 74  semantics used t
2c5a0 6f 0a 2a 2a 20 6e 6f 72 6d 61 6c 69 7a 65 20 61  o.** normalize a
2c5b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
2c5c0 72 65 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  re unspecified a
2c5d0 6e 64 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  nd subject to ch
2c5e0 61 6e 67 65 2e 0a 2a 2a 20 41 74 20 61 20 6d 69  ange..** At a mi
2c5f0 6e 69 6d 75 6d 2c 20 6c 69 74 65 72 61 6c 20 76  nimum, literal v
2c600 61 6c 75 65 73 20 77 69 6c 6c 20 62 65 20 72 65  alues will be re
2c610 70 6c 61 63 65 64 20 77 69 74 68 20 73 75 69 74  placed with suit
2c620 61 62 6c 65 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  able.** placehol
2c630 64 65 72 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  ders..** </dl>.*
2c640 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2c650 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54  _PREPARE_PERSIST
2c660 45 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ENT             
2c670 20 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51   0x01.#define SQ
2c680 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 52  LITE_PREPARE_NOR
2c690 4d 41 4c 49 5a 45 20 20 20 20 20 20 20 20 20 20  MALIZE          
2c6a0 20 20 20 20 20 30 78 30 32 0a 0a 2f 2a 0a 2a 2a       0x02../*.**
2c6b0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
2c6c0 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74  ling An SQL Stat
2c6d0 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  ement.** KEYWORD
2c6e0 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e  S: {SQL statemen
2c6f0 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d  t compiler}.** M
2c700 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
2c710 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73  * CONSTRUCTOR: s
2c720 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2c730 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20  * To execute an 
2c740 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69  SQL statement, i
2c750 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
2c760 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
2c770 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
2c780 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
2c790 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2c7a0 2e 20 20 4f 72 2c 20 69 6e 20 6f 74 68 65 72 20  .  Or, in other 
2c7b0 77 6f 72 64 73 2c 20 74 68 65 73 65 20 72 6f 75  words, these rou
2c7c0 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 63 6f 6e  tines.** are con
2c7d0 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20 74 68  structors for th
2c7e0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2c7f0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a  ement] object..*
2c800 2a 0a 2a 2a 20 54 68 65 20 70 72 65 66 65 72 72  *.** The preferr
2c810 65 64 20 72 6f 75 74 69 6e 65 20 74 6f 20 75 73  ed routine to us
2c820 65 20 69 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  e is [sqlite3_pr
2c830 65 70 61 72 65 5f 76 32 28 29 5d 2e 20 20 54 68  epare_v2()].  Th
2c840 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
2c850 65 70 61 72 65 28 29 5d 20 69 6e 74 65 72 66 61  epare()] interfa
2c860 63 65 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64  ce is legacy and
2c870 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64   should be avoid
2c880 65 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ed..** [sqlite3_
2c890 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 68 61  prepare_v3()] ha
2c8a0 73 20 61 6e 20 65 78 74 72 61 20 22 70 72 65 70  s an extra "prep
2c8b0 46 6c 61 67 73 22 20 6f 70 74 69 6f 6e 20 74 68  Flags" option th
2c8c0 61 74 20 69 73 20 75 73 65 64 0a 2a 2a 20 66 6f  at is used.** fo
2c8d0 72 20 73 70 65 63 69 61 6c 20 70 75 72 70 6f 73  r special purpos
2c8e0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 73  es..**.** The us
2c8f0 65 20 6f 66 20 74 68 65 20 55 54 46 2d 38 20 69  e of the UTF-8 i
2c900 6e 74 65 72 66 61 63 65 73 20 69 73 20 70 72 65  nterfaces is pre
2c910 66 65 72 72 65 64 2c 20 61 73 20 53 51 4c 69 74  ferred, as SQLit
2c920 65 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 64  e currently.** d
2c930 6f 65 73 20 61 6c 6c 20 70 61 72 73 69 6e 67 20  oes all parsing 
2c940 75 73 69 6e 67 20 55 54 46 2d 38 2e 20 20 54 68  using UTF-8.  Th
2c950 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72 66 61  e UTF-16 interfa
2c960 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
2c970 0a 2a 2a 20 61 73 20 61 20 63 6f 6e 76 65 6e 69  .** as a conveni
2c980 65 6e 63 65 2e 20 20 54 68 65 20 55 54 46 2d 31  ence.  The UTF-1
2c990 36 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72  6 interfaces wor
2c9a0 6b 20 62 79 20 63 6f 6e 76 65 72 74 69 6e 67 20  k by converting 
2c9b0 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 74 65 78  the.** input tex
2c9c0 74 20 69 6e 74 6f 20 55 54 46 2d 38 2c 20 74 68  t into UTF-8, th
2c9d0 65 6e 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  en invoking the 
2c9e0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 55 54  corresponding UT
2c9f0 46 2d 38 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  F-8 interface..*
2ca00 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
2ca10 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69  rgument, "db", i
2ca20 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  s a [database co
2ca30 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e  nnection] obtain
2ca40 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69  ed from a.** pri
2ca50 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
2ca60 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ll to [sqlite3_o
2ca70 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
2ca80 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a  _open_v2()] or.*
2ca90 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
2caa0 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62  6()].  The datab
2cab0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
2cac0 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65  ust not have bee
2cad0 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  n closed..**.** 
2cae0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
2caf0 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20  ent, "zSql", is 
2cb00 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  the statement to
2cb10 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e   be compiled, en
2cb20 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68  coded.** as eith
2cb30 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
2cb40 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  16.  The sqlite3
2cb50 5f 70 72 65 70 61 72 65 28 29 2c 20 73 71 6c 69  _prepare(), sqli
2cb60 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2cb70 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  ,.** and sqlite3
2cb80 5f 70 72 65 70 61 72 65 5f 76 33 28 29 0a 2a 2a  _prepare_v3().**
2cb90 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
2cba0 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
2cbb0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 2c 20  e3_prepare16(), 
2cbc0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2cbd0 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73  6_v2(),.** and s
2cbe0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2cbf0 5f 76 33 28 29 20 75 73 65 20 55 54 46 2d 31 36  _v3() use UTF-16
2cc00 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2cc10 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
2cc20 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
2cc30 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
2cc40 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
2cc50 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2cc60 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70  . ^If nByte is p
2cc70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74  ositive, then it
2cc80 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
2cc90 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64 20  r of bytes read 
2cca0 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20  from zSql.  ^If 
2ccb0 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74  nByte is zero, t
2ccc0 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a  hen no prepared.
2ccd0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ** statement is 
2cce0 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66  generated..** If
2ccf0 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77   the caller know
2cd00 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  s that the suppl
2cd10 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
2cd20 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
2cd30 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61  en.** there is a
2cd40 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e   small performan
2cd50 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
2cd60 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
2cd70 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a   parameter that.
2cd80 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
2cd90 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2cda0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
2cdb0 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a  >including</i>.*
2cdc0 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e  * the nul-termin
2cdd0 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ator..**.** ^If 
2cde0 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
2cdf0 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
2ce00 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
2ce10 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
2ce20 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
2ce30 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
2ce40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
2ce50 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
2ce60 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
2ce70 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
2ce80 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
2ce90 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
2cea0 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
2ceb0 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
2cec0 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
2ced0 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
2cee0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
2cef0 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
2cf00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2cf10 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
2cf20 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
2cf30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2cf40 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
2cf50 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
2cf60 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
2cf70 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
2cf80 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
2cf90 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
2cfa0 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
2cfb0 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
2cfc0 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
2cfd0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
2cfe0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
2cff0 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
2d000 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
2d010 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
2d020 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
2d030 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
2d040 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2d050 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
2d060 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
2d070 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
2d080 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
2d090 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
2d0a0 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
2d0b0 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
2d0c0 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
2d0d0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
2d0e0 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
2d0f0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
2d100 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2d110 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
2d120 61 72 65 5f 76 32 28 29 2c 20 73 71 6c 69 74 65  are_v2(), sqlite
2d130 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 2c 20  3_prepare_v3(), 
2d140 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2d150 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73  6_v2(),.** and s
2d160 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2d170 5f 76 33 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v3() interfaces
2d180 20 61 72 65 20 72 65 63 6f 6d 6d 65 6e 64 65 64   are recommended
2d190 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
2d1a0 67 72 61 6d 73 2e 0a 2a 2a 20 54 68 65 20 6f 6c  grams..** The ol
2d1b0 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 28  der interfaces (
2d1c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2d1d0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
2d1e0 65 70 61 72 65 31 36 28 29 29 0a 2a 2a 20 61 72  epare16()).** ar
2d1f0 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62  e retained for b
2d200 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
2d210 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
2d220 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
2d230 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65  aged..** ^In the
2d240 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73   "vX" interfaces
2d250 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
2d260 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
2d270 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
2d280 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
2d290 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
2d2a0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
2d2b0 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
2d2c0 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
2d2d0 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
2d2e0 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
2d2f0 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69   to.** behave di
2d300 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72  fferently in thr
2d310 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ee ways:.**.** <
2d320 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  ol>.** <li>.** ^
2d330 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
2d340 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20  schema changes, 
2d350 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72  instead of retur
2d360 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48  ning [SQLITE_SCH
2d370 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c  EMA] as it.** al
2d380 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c  ways used to do,
2d390 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2d3a0 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ] will automatic
2d3b0 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74  ally recompile t
2d3c0 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  he SQL.** statem
2d3d0 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72  ent and try to r
2d3e0 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20  un it again. As 
2d3f0 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f  many as [SQLITE_
2d400 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59  MAX_SCHEMA_RETRY
2d410 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c  ].** retries wil
2d420 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73  l occur before s
2d430 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67 69  qlite3_step() gi
2d440 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75 72  ves up and retur
2d450 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20  ns an error..** 
2d460 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
2d470 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72  .** ^When an err
2d480 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69  or occurs, [sqli
2d490 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
2d4a0 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74   return one of t
2d4b0 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b  he detailed.** [
2d4c0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20  error codes] or 
2d4d0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
2d4e0 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65  codes].  ^The le
2d4f0 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
2d500 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74  s that.** [sqlit
2d510 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
2d520 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
2d530 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45  eneric [SQLITE_E
2d540 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
2d550 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70  e.** and the app
2d560 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68  lication would h
2d570 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65  ave to make a se
2d580 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cond call to [sq
2d590 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
2d5a0 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  * in order to fi
2d5b0 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
2d5c0 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  g cause of the p
2d5d0 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65  roblem. With the
2d5e0 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a   "v2" prepare.**
2d5f0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
2d600 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73   underlying reas
2d610 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72  on for the error
2d620 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
2d630 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c  ediately..** </l
2d640 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
2d650 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
2d660 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f  c value bound to
2d670 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f   [parameter | ho
2d680 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  st parameter] in
2d690 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63   the .** WHERE c
2d6a0 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c  lause might infl
2d6b0 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65  uence the choice
2d6c0 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66   of query plan f
2d6d0 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a  or a statement,.
2d6e0 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74  ** then the stat
2d6f0 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75  ement will be au
2d700 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
2d710 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68  mpiled, as if th
2d720 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a  ere had been .**
2d730 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
2d740 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20  , on the first  
2d750 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2d760 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20   call following 
2d770 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f  any change.** to
2d780 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
2d790 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e  nd_text | bindin
2d7a0 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72  gs] of that [par
2d7b0 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68  ameter]. .** ^Th
2d7c0 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
2d7d0 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65   of WHERE-clause
2d7e0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67   [parameter] mig
2d7f0 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
2d800 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71   .** choice of q
2d810 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65  uery plan if the
2d820 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2d830 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  e left-hand side
2d840 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20   of a [LIKE].** 
2d850 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  or [GLOB] operat
2d860 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72  or or if the par
2d870 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72  ameter is compar
2d880 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64  ed to an indexed
2d890 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74   column.** and t
2d8a0 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  he [SQLITE_ENABL
2d8b0 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65  E_STAT3] compile
2d8c0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
2d8d0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69  enabled..** </li
2d8e0 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ol>.**.**
2d8f0 20 3c 70 3e 5e 73 71 6c 69 74 65 33 5f 70 72 65   <p>^sqlite3_pre
2d900 70 61 72 65 5f 76 33 28 29 20 64 69 66 66 65 72  pare_v3() differ
2d910 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 70  s from sqlite3_p
2d920 72 65 70 61 72 65 5f 76 32 28 29 20 6f 6e 6c 79  repare_v2() only
2d930 20 69 6e 20 68 61 76 69 6e 67 0a 2a 2a 20 74 68   in having.** th
2d940 65 20 65 78 74 72 61 20 70 72 65 70 46 6c 61 67  e extra prepFlag
2d950 73 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69  s parameter, whi
2d960 63 68 20 69 73 20 61 20 62 69 74 20 61 72 72 61  ch is a bit arra
2d970 79 20 63 6f 6e 73 69 73 74 69 6e 67 20 6f 66 20  y consisting of 
2d980 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20  zero or.** more 
2d990 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 50  of the [SQLITE_P
2d9a0 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e  REPARE_PERSISTEN
2d9b0 54 7c 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  T|SQLITE_PREPARE
2d9c0 5f 2a 5d 20 66 6c 61 67 73 2e 20 20 5e 54 68 65  _*] flags.  ^The
2d9d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
2d9e0 61 72 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61  are_v2() interfa
2d9f0 63 65 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79  ce works exactly
2da00 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20   the same as.** 
2da10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2da20 76 33 28 29 20 77 69 74 68 20 61 20 7a 65 72 6f  v3() with a zero
2da30 20 70 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d   prepFlags param
2da40 65 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  eter..*/.int sql
2da50 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20  ite3_prepare(.  
2da60 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2da70 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2da80 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
2da90 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
2daa0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
2dab0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
2dac0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2dad0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2dae0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2daf0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2db00 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2db10 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2db20 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2db30 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2db40 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2db50 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2db60 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2db70 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2db80 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
2db90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2dba0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
2dbb0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2dbc0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2dbd0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2dbe0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2dbf0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2dc00 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
2dc10 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2dc20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2dc30 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2dc40 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2dc50 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2dc60 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2dc70 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2dc80 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2dc90 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
2dca0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2dcb0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2dcc0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2dcd0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
2dce0 65 70 61 72 65 5f 76 33 28 0a 20 20 73 71 6c 69  epare_v3(.  sqli
2dcf0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2dd00 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2dd10 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2dd20 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
2dd30 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
2dd40 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
2dd50 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2dd60 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2dd70 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2dd80 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2dd90 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 6e  tes. */.  unsign
2dda0 65 64 20 69 6e 74 20 70 72 65 70 46 6c 61 67 73  ed int prepFlags
2ddb0 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f 72  , /* Zero or mor
2ddc0 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  e SQLITE_PREPARE
2ddd0 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71 6c  _ flags */.  sql
2dde0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2ddf0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2de00 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2de10 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
2de20 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2de30 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2de40 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2de50 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
2de60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2de70 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2de80 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2de90 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2dea0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2deb0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2dec0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2ded0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
2dee0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2def0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2df00 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2df10 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2df20 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2df30 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2df40 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2df50 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2df60 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
2df70 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2df80 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2df90 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2dfa0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
2dfb0 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c  pare16_v2(.  sql
2dfc0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2dfd0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2dfe0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2dff0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
2e000 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2e010 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
2e020 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2e030 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2e040 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2e050 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2e060 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
2e070 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2e080 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2e090 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2e0a0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
2e0b0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2e0c0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2e0d0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2e0e0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
2e0f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2e100 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v3(.  sqlite3 *d
2e110 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2e120 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2e130 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2e140 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2e150 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2e160 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
2e170 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2e180 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2e190 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2e1a0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2e1b0 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 6e  */.  unsigned in
2e1c0 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20  t prepFlags, /* 
2e1d0 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c  Zero or more SQL
2e1e0 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c 61  ITE_PREPARE_ fla
2e1f0 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  gs */.  sqlite3_
2e200 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2e210 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2e220 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2e230 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
2e240 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2e250 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2e260 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2e270 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
2e280 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e  I3REF: Retrievin
2e290 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a  g Statement SQL.
2e2a0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2e2b0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2e2c0 68 65 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50  he sqlite3_sql(P
2e2d0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2e2e0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2e2f0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 55   a copy of the U
2e300 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78 74  TF-8.** SQL text
2e310 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
2e320 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2e330 65 6e 74 5d 20 50 20 69 66 20 50 20 77 61 73 0a  ent] P if P was.
2e340 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 5b 73  ** created by [s
2e350 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2e360 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70  2()], [sqlite3_p
2e370 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 0a 2a 2a  repare_v3()],.**
2e380 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e390 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b 73  e16_v2()], or [s
2e3a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2e3b0 5f 76 33 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  _v3()]..** ^The 
2e3c0 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2e3d0 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63  _sql(P) interfac
2e3e0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2e3f0 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a 2a  ter to a UTF-8.*
2e400 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
2e410 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65 78 74  ing the SQL text
2e420 20 6f 66 20 70 72 65 70 61 72 65 64 20 73 74 61   of prepared sta
2e430 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a 2a  tement P with.**
2e440 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65   [bound paramete
2e450 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a 2a  rs] expanded..**
2e460 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6e 6f   ^The sqlite3_no
2e470 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 50 29 20  rmalized_sql(P) 
2e480 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2e490 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
2e4a0 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67   UTF-8.** string
2e4b0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
2e4c0 6e 6f 72 6d 61 6c 69 7a 65 64 20 53 51 4c 20 74  normalized SQL t
2e4d0 65 78 74 20 6f 66 20 70 72 65 70 61 72 65 64 20  ext of prepared 
2e4e0 73 74 61 74 65 6d 65 6e 74 20 50 2e 20 20 54 68  statement P.  Th
2e4f0 65 0a 2a 2a 20 73 65 6d 61 6e 74 69 63 73 20 75  e.** semantics u
2e500 73 65 64 20 74 6f 20 6e 6f 72 6d 61 6c 69 7a 65  sed to normalize
2e510 20 61 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74   a SQL statement
2e520 20 61 72 65 20 75 6e 73 70 65 63 69 66 69 65 64   are unspecified
2e530 20 61 6e 64 20 73 75 62 6a 65 63 74 0a 2a 2a 20   and subject.** 
2e540 74 6f 20 63 68 61 6e 67 65 2e 20 20 41 74 20 61  to change.  At a
2e550 20 6d 69 6e 69 6d 75 6d 2c 20 6c 69 74 65 72 61   minimum, litera
2e560 6c 20 76 61 6c 75 65 73 20 77 69 6c 6c 20 62 65  l values will be
2e570 20 72 65 70 6c 61 63 65 64 20 77 69 74 68 20 73   replaced with s
2e580 75 69 74 61 62 6c 65 0a 2a 2a 20 70 6c 61 63 65  uitable.** place
2e590 68 6f 6c 64 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  holders..**.** ^
2e5a0 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  (For example, if
2e5b0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2e5c0 65 6d 65 6e 74 20 69 73 20 63 72 65 61 74 65 64  ement is created
2e5d0 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a   using the SQL.*
2e5e0 2a 20 74 65 78 74 20 22 53 45 4c 45 43 54 20 24  * text "SELECT $
2e5f0 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66  abc,:xyz" and if
2e600 20 70 61 72 61 6d 65 74 65 72 20 24 61 62 63 20   parameter $abc 
2e610 69 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65  is bound to inte
2e620 67 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20  ger 2345.** and 
2e630 70 61 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69  parameter :xyz i
2e640 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20  s unbound, then 
2e650 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69  sqlite3_sql() wi
2e660 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  ll return.** the
2e670 20 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67   original string
2e680 2c 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a  , "SELECT $abc,:
2e690 78 79 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33  xyz" but sqlite3
2e6a0 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a  _expanded_sql().
2e6b0 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22  ** will return "
2e6c0 53 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c  SELECT 2345,NULL
2e6d0 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ".)^.**.** ^The 
2e6e0 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2e6f0 5f 73 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65  _sql() interface
2e700 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66   returns NULL if
2e710 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65   insufficient me
2e720 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c  mory.** is avail
2e730 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65  able to hold the
2e740 20 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74   result, or if t
2e750 68 65 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20  he result would 
2e760 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68  exceed the.** th
2e770 65 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67  e maximum string
2e780 20 6c 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e   length determin
2e790 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  ed by the [SQLIT
2e7a0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e  E_LIMIT_LENGTH].
2e7b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
2e7c0 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c  ITE_TRACE_SIZE_L
2e7d0 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  IMIT] compile-ti
2e7e0 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73  me option limits
2e7f0 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20   the size of.** 
2e800 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20  bound parameter 
2e810 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68  expansions.  ^Th
2e820 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54  e [SQLITE_OMIT_T
2e830 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  RACE] compile-ti
2e840 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75  me.** option cau
2e850 73 65 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61  ses sqlite3_expa
2e860 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c  nded_sql() to al
2e870 77 61 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c  ways return NULL
2e880 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72  ..**.** ^The str
2e890 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
2e8a0 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20   sqlite3_sql(P) 
2e8b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6e 6f 72 6d  and sqlite3_norm
2e8c0 61 6c 69 7a 65 64 5f 73 71 6c 28 50 29 0a 2a 2a  alized_sql(P).**
2e8d0 20 61 72 65 20 6d 61 6e 61 67 65 64 20 62 79 20   are managed by 
2e8e0 53 51 4c 69 74 65 20 61 6e 64 20 61 72 65 20 61  SQLite and are a
2e8f0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
2e900 65 64 20 77 68 65 6e 20 74 68 65 20 70 72 65 70  ed when the prep
2e910 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
2e920 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 2e 0a  t is finalized..
2e930 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72  ** ^The string r
2e940 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2e950 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2e960 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68 65 72  P), on the other
2e970 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62 74   hand,.** is obt
2e980 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2e990 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
2e9a0 64 20 6d 75 73 74 20 62 65 20 66 72 65 65 20 62  d must be free b
2e9b0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
2e9c0 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e 67 20  n.** by passing 
2e9d0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  it to [sqlite3_f
2e9e0 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  ree()]..*/.const
2e9f0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
2ea00 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
2ea10 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72 20 2a 73  *pStmt);.char *s
2ea20 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2ea30 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
2ea40 20 2a 70 53 74 6d 74 29 3b 0a 63 6f 6e 73 74 20   *pStmt);.const 
2ea50 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6e 6f  char *sqlite3_no
2ea60 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 73 71 6c  rmalized_sql(sql
2ea70 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2ea80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ea90 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
2eaa0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
2eab0 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
2eac0 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a  abase.** METHOD:
2ead0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2eae0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2eaf0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58  _stmt_readonly(X
2eb00 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2eb10 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
2eb20 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e  ro) if.** and on
2eb30 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61  ly if the [prepa
2eb40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58  red statement] X
2eb50 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74   makes no direct
2eb60 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74   changes to.** t
2eb70 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
2eb80 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
2eb90 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2eba0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2ebb0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2ebc0 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74  ons] or.** [virt
2ebd0 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68  ual tables] migh
2ebe0 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
2ebf0 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79  abase indirectly
2ec00 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63   as a side effec
2ec10 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  t.  .** ^(For ex
2ec20 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70  ample, if an app
2ec30 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73  lication defines
2ec40 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61   a function "eva
2ec50 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61  l()" that .** ca
2ec60 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  lls [sqlite3_exe
2ec70 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66  c()], then the f
2ec80 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61  ollowing SQL sta
2ec90 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20  tement would.** 
2eca0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2ecb0 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68  ase file through
2ecc0 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a   side-effects:.*
2ecd0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
2ece0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c  ><pre>.**    SEL
2ecf0 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45  ECT eval('DELETE
2ed00 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20   FROM t1') FROM 
2ed10 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  t2;.** </pre></b
2ed20 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
2ed30 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65   But because the
2ed40 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2ed50 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ent does not cha
2ed60 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
2ed70 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c   file.** directl
2ed80 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  y, sqlite3_stmt_
2ed90 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64  readonly() would
2eda0 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72   still return tr
2edb0 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61  ue.)^.**.** ^Tra
2edc0 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
2edd0 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68   statements such
2ede0 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f   as [BEGIN], [CO
2edf0 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b  MMIT], [ROLLBACK
2ee00 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54  ],.** [SAVEPOINT
2ee10 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d  ], and [RELEASE]
2ee20 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73   cause sqlite3_s
2ee30 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
2ee40 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a  o return true,.*
2ee50 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74  * since the stat
2ee60 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65  ements themselve
2ee70 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c  s do not actuall
2ee80 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  y modify the dat
2ee90 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74  abase but.** rat
2eea0 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c  her they control
2eeb0 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77   the timing of w
2eec0 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d  hen other statem
2eed0 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20  ents modify the 
2eee0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e  .** database.  ^
2eef0 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64  The [ATTACH] and
2ef00 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d   [DETACH] statem
2ef10 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a  ents also cause.
2ef20 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
2ef30 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
2ef40 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c  turn true since,
2ef50 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61   while those sta
2ef60 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67  tements.** chang
2ef70 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  e the configurat
2ef80 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73  ion of a databas
2ef90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68  e connection, th
2efa0 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a  ey do not make .
2efb0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ** changes to th
2efc0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2efd0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
2efe0 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65  on disk..** ^The
2eff0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2f000 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66 61  adonly() interfa
2f010 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
2f020 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e 63  for [BEGIN] sinc
2f030 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65 72  e.** [BEGIN] mer
2f040 65 6c 79 20 73 65 74 73 20 69 6e 74 65 72 6e 61  ely sets interna
2f050 6c 20 66 6c 61 67 73 2c 20 62 75 74 20 74 68 65  l flags, but the
2f060 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 49 4d   [BEGIN|BEGIN IM
2f070 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a 20  MEDIATE] and.** 
2f080 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 45 58 43  [BEGIN|BEGIN EXC
2f090 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64 73  LUSIVE] commands
2f0a0 20 64 6f 20 74 6f 75 63 68 20 74 68 65 20 64 61   do touch the da
2f0b0 74 61 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a 2a  tabase and so.**
2f0c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2f0d0 61 64 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e 73  adonly() returns
2f0e0 20 66 61 6c 73 65 20 66 6f 72 20 74 68 6f 73 65   false for those
2f0f0 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 69 6e   commands..*/.in
2f100 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  t sqlite3_stmt_r
2f110 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f  eadonly(sqlite3_
2f120 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2f130 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2f140 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72  etermine If A Pr
2f150 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2f160 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a   Has Been Reset.
2f170 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2f180 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2f190 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
2f1a0 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63  busy(S) interfac
2f1b0 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
2f1c0 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65  non-zero) if the
2f1d0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2f1e0 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62  atement] S has b
2f1f0 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c  een stepped at l
2f200 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20  east once using 
2f210 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2f220 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65  p(S)] but has ne
2f230 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d  ither run to com
2f240 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65  pletion (returne
2f250 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  d.** [SQLITE_DON
2f260 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  E] from [sqlite3
2f270 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a  _step(S)]) nor.*
2f280 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69  * been reset usi
2f290 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
2f2a0 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c  t(S)].  ^The sql
2f2b0 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
2f2c0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
2f2d0 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20  eturns false if 
2f2e0 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  S is a NULL poin
2f2f0 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f  ter.  If S is no
2f300 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  t a .** NULL poi
2f310 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20  nter and is not 
2f320 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
2f330 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73  alid [prepared s
2f340 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
2f350 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ect, then the be
2f360 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
2f370 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
2f380 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a   undesirable..**
2f390 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2f3a0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ce can be used i
2f3b0 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73  n combination [s
2f3c0 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
2f3d0 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65  ()].** to locate
2f3e0 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74   all prepared st
2f3f0 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61  atements associa
2f400 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62  ted with a datab
2f410 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  ase .** connecti
2f420 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e  on that are in n
2f430 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73  eed of being res
2f440 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65  et.  This can be
2f450 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78   used,.** for ex
2f460 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f  ample, in diagno
2f470 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f  stic routines to
2f480 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70   search for prep
2f490 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65  ared .** stateme
2f4a0 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c  nts that are hol
2f4b0 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69  ding a transacti
2f4c0 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20  on open..*/.int 
2f4d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2f4e0 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  y(sqlite3_stmt*)
2f4f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f500 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
2f510 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
2f520 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
2f530 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2f540 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
2f550 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2f560 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
2f570 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
2f580 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2f590 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
2f5a0 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
2f5b0 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
2f5c0 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
2f5d0 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
2f5e0 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
2f5f0 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
2f600 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c  it stores.  ^Val
2f610 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
2f620 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2f630 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
2f640 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
2f650 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
2f660 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
2f670 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
2f680 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2f690 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
2f6a0 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
2f6b0 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
2f6c0 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
2f6d0 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
2f6e0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2f6f0 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
2f700 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
2f710 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
2f720 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
2f730 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
2f740 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
2f750 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
2f760 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
2f770 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
2f780 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
2f790 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
2f7a0 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
2f7b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2f7c0 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20  _value.  The.** 
2f7d0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64  [sqlite3_value_d
2f7e0 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  up()] interface 
2f7f0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
2f800 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a  onstruct a new .
2f810 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  ** protected sql
2f820 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20  ite3_value from 
2f830 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
2f840 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
2f850 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
2f860 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
2f870 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
2f880 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
2f890 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
2f8a0 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65  s held.  An inte
2f8b0 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
2f8c0 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
2f8d0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2f8e0 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
2f8f0 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
2f900 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
2f910 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2f920 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
2f930 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
2f940 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
2f950 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
2f960 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
2f970 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
2f980 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
2f990 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
2f9a0 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
2f9b0 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
2f9c0 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
2f9d0 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
2f9e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
2f9f0 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
2fa00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
2fa10 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
2fa20 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
2fa30 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
2fa40 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
2fa50 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
2fa60 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2fa70 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
2fa80 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
2fa90 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
2faa0 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
2fab0 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
2fac0 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
2fad0 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
2fae0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
2faf0 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
2fb00 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
2fb10 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
2fb20 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2fb30 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2fb40 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
2fb50 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
2fb60 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2fb70 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2fb80 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
2fb90 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
2fba0 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
2fbb0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2fbc0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2fbd0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2fbe0 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
2fbf0 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
2fc00 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2fc10 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2fc20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2fc30 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
2fc40 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
2fc50 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2fc60 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
2fc70 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 61 73   only be used as
2fc80 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f   arguments.** to
2fc90 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2fca0 5f 76 61 6c 75 65 28 29 5d 2c 20 5b 73 71 6c 69  _value()], [sqli
2fcb0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
2fcc0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2fcd0 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e  e3_value_dup()].
2fce0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
2fcf0 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
2fd00 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
2fd10 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
2fd20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
2fd30 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
2fd40 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2fd50 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
2fd60 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
2fd70 61 6c 75 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  alue sqlite3_val
2fd80 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
2fd90 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
2fda0 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
2fdb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
2fdc0 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
2fdd0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
2fde0 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
2fdf0 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
2fe00 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
2fe10 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
2fe20 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
2fe30 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
2fe40 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
2fe50 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
2fe60 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2fe70 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
2fe80 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
2fe90 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2fea0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2feb0 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
2fec0 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
2fed0 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
2fee0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
2fef0 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
2ff00 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
2ff10 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
2ff20 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
2ff30 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
2ff40 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
2ff50 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
2ff60 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
2ff70 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
2ff80 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
2ff90 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2ffa0 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
2ffb0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
2ffc0 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
2ffd0 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
2ffe0 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
2fff0 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
30000 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
30010 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
30020 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
30030 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
30040 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
30050 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
30060 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
30070 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
30080 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
30090 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44  nding}.** METHOD
300a0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
300b0 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
300c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
300d0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
300e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
300f0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
30100 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
30110 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
30120 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
30130 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
30140 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
30150 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
30160 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
30170 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
30180 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
30190 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
301a0 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
301b0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
301c0 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
301d0 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
301e0 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
301f0 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
30200 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
30210 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
30220 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
30230 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
30240 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
30250 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
30260 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
30270 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
30280 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
30290 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
302a0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
302b0 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
302c0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
302d0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
302e0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
302f0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
30300 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
30310 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
30320 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
30330 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
30340 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
30350 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
30360 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
30370 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
30380 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
30390 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
303a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
303b0 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
303c0 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
303d0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
303e0 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
303f0 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
30400 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
30410 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
30420 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
30430 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
30440 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
30450 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
30460 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
30470 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
30480 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
30490 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
304a0 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
304b0 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
304c0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
304d0 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
304e0 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
304f0 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
30500 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
30510 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
30520 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
30530 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
30540 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
30550 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
30560 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
30570 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
30580 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
30590 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
305a0 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
305b0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
305c0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
305d0 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
305e0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
305f0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
30600 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
30610 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
30620 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
30630 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
30640 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e  nd_blob() is a N
30650 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
30660 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
30670 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f  meter.** is igno
30680 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20  red and the end 
30690 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61  result is the sa
306a0 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69  me as sqlite3_bi
306b0 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a  nd_null()..**.**
306c0 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74   ^(In those rout
306d0 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
306e0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
306f0 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
30700 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
30710 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
30720 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
30730 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
30740 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
30750 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
30760 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
30770 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
30780 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a   characters.)^.*
30790 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68  * ^If the fourth
307a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
307b0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
307c0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
307d0 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73  d_text16().** is
307e0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
307f0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
30800 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
30810 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
30820 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
30830 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
30840 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f  or..** If the fo
30850 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
30860 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
30870 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76  lob() is negativ
30880 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62  e, then.** the b
30890 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
308a0 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f  ined..** If a no
308b0 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74  n-negative fourt
308c0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  h parameter is p
308d0 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74  rovided to sqlit
308e0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a  e3_bind_text().*
308f0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
30900 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71  d_text16() or sq
30910 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
30920 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74  4() then.** that
30930 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
30940 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
30950 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20  et.** where the 
30960 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
30970 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d  ould occur assum
30980 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77  ing the string w
30990 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69  ere NUL.** termi
309a0 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
309b0 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
309c0 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73  cur at byte offs
309d0 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a  ets less than .*
309e0 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * the value of t
309f0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
30a00 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73  ter then the res
30a10 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61  ulting string va
30a20 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  lue will.** cont
30a30 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
30a40 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f  s.  The result o
30a50 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  f expressions in
30a60 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a  volving strings.
30a70 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  ** with embedded
30a80 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
30a90 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
30aa0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
30ab0 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74   the BLOB and st
30ac0 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74  ring binding int
30ad0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20  erfaces.** is a 
30ae0 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
30af0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
30b00 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
30b10 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
30b20 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
30b30 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
30b40 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
30b50 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
30b60 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
30b70 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
30b80 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41  e call to bind A
30b90 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66  PI fails..** ^If
30ba0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
30bb0 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
30bc0 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
30bd0 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
30be0 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
30bf0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
30c00 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
30c10 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
30c20 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
30c30 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
30c40 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
30c50 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
30c60 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
30c70 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
30c80 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
30c90 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
30ca0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
30cb0 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
30cc0 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
30cd0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
30ce0 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
30cf0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
30d00 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
30d10 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
30d20 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20  ext64() must be 
30d30 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54  one of.** [SQLIT
30d40 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
30d50 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45  _UTF16], [SQLITE
30d60 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53  _UTF16BE], or [S
30d70 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a  QLITE_UTF16LE].*
30d80 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  * to specify the
30d90 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65   encoding of the
30da0 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69   text in the thi
30db0 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  rd parameter.  I
30dc0 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61  f.** the sixth a
30dd0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
30de0 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
30df0 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
30e00 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61  he.** allowed va
30e10 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  lues shown above
30e20 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74  , or if the text
30e30 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
30e40 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74  ferent.** from t
30e50 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
30e60 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78  ified by the six
30e70 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  th parameter, th
30e80 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
30e90 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
30ea0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
30eb0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
30ec0 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
30ed0 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
30ee0 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
30ef0 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
30f00 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
30f10 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
30f20 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
30f30 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
30f40 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
30f50 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
30f60 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
30f70 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
30f80 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
30f90 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
30fa0 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
30fb0 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
30fc0 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
30fd0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
30fe0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
30ff0 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
31000 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
31010 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
31020 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
31030 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
31040 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
31050 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  OB..**.** ^The s
31060 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e  qlite3_bind_poin
31070 74 65 72 28 53 2c 49 2c 50 2c 54 2c 44 29 20 72  ter(S,I,P,T,D) r
31080 6f 75 74 69 6e 65 20 63 61 75 73 65 73 20 74 68  outine causes th
31090 65 20 49 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e I-th parameter
310a0 20 69 6e 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64   in.** [prepared
310b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 74 6f   statement] S to
310c0 20 68 61 76 65 20 61 6e 20 53 51 4c 20 76 61 6c   have an SQL val
310d0 75 65 20 6f 66 20 4e 55 4c 4c 2c 20 62 75 74 20  ue of NULL, but 
310e0 74 6f 20 61 6c 73 6f 20 62 65 0a 2a 2a 20 61 73  to also be.** as
310f0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
31100 65 20 70 6f 69 6e 74 65 72 20 50 20 6f 66 20 74  e pointer P of t
31110 79 70 65 20 54 2e 20 20 5e 44 20 69 73 20 65 69  ype T.  ^D is ei
31120 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
31130 74 65 72 20 6f 72 0a 2a 2a 20 61 20 70 6f 69 6e  ter or.** a poin
31140 74 65 72 20 74 6f 20 61 20 64 65 73 74 72 75 63  ter to a destruc
31150 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72  tor function for
31160 20 50 2e 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c   P. ^SQLite will
31170 20 69 6e 76 6f 6b 65 20 74 68 65 0a 2a 2a 20 64   invoke the.** d
31180 65 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 68  estructor D with
31190 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
311a0 6e 74 20 6f 66 20 50 20 77 68 65 6e 20 69 74 20  nt of P when it 
311b0 69 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  is finished usin
311c0 67 0a 2a 2a 20 50 2e 20 20 54 68 65 20 54 20 70  g.** P.  The T p
311d0 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
311e0 62 65 20 61 20 73 74 61 74 69 63 20 73 74 72 69  be a static stri
311f0 6e 67 2c 20 70 72 65 66 65 72 61 62 6c 79 20 61  ng, preferably a
31200 20 73 74 72 69 6e 67 0a 2a 2a 20 6c 69 74 65 72   string.** liter
31210 61 6c 2e 20 54 68 65 20 73 71 6c 69 74 65 33 5f  al. The sqlite3_
31220 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 29 20 72  bind_pointer() r
31230 6f 75 74 69 6e 65 20 69 73 20 70 61 72 74 20 6f  outine is part o
31240 66 20 74 68 65 0a 2a 2a 20 5b 70 6f 69 6e 74 65  f the.** [pointe
31250 72 20 70 61 73 73 69 6e 67 20 69 6e 74 65 72 66  r passing interf
31260 61 63 65 5d 20 61 64 64 65 64 20 66 6f 72 20 53  ace] added for S
31270 51 4c 69 74 65 20 33 2e 32 30 2e 30 2e 0a 2a 2a  QLite 3.20.0..**
31280 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74  .** ^If any of t
31290 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
312a0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  *() routines are
312b0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
312c0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66  ULL pointer.** f
312d0 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
312e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77   statement] or w
312f0 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73  ith a prepared s
31300 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69  tatement for whi
31310 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  ch.** [sqlite3_s
31320 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20  tep()] has been 
31330 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65  called more rece
31340 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74  ntly than [sqlit
31350 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20  e3_reset()],.** 
31360 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69  then the call wi
31370 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
31380 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61  E_MISUSE].  If a
31390 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ny sqlite3_bind_
313a0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73  ().** routine is
313b0 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61   passed a [prepa
313c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
313d0 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e  hat has been fin
313e0 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72  alized, the.** r
313f0 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
31400 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
31410 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
31420 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
31430 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
31440 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
31450 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55  ] routine..** ^U
31460 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
31470 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
31480 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
31490 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
314a0 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65  nd_* routines re
314b0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
314c0 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
314d0 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  n.** [error code
314e0 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f  ] if anything go
314f0 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53  es wrong..** ^[S
31500 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69  QLITE_TOOBIG] mi
31510 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
31520 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  if the size of a
31530 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a   string or BLOB.
31540 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74  ** exceeds limit
31550 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71  s imposed by [sq
31560 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
31570 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
31580 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  H]) or.** [SQLIT
31590 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a  E_MAX_LENGTH]..*
315a0 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
315b0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
315c0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
315d0 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
315e0 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
315f0 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
31600 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
31610 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
31620 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
31630 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
31640 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
31650 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
31660 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
31670 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
31680 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
31690 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
316a0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
316b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
316c0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
316d0 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
316e0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
316f0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73  e3_bind_blob64(s
31700 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
31710 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
31720 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a  sqlite3_uint64,.
31730 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31740 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28          void(*)(
31750 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
31760 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
31770 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31780 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e  int, double);.in
31790 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
317a0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
317b0 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74  , int, int);.int
317c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
317d0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
317e0 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
317f0 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69  int64);.int sqli
31800 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71  te3_bind_null(sq
31810 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
31820 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
31830 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
31840 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74  _stmt*,int,const
31850 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28   char*,int,void(
31860 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
31870 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
31880 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
31890 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
318a0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
318b0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
318c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
318d0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
318e0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
318f0 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  r*, sqlite3_uint
31900 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
31910 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
31920 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73  d(*)(void*), uns
31930 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64  igned char encod
31940 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ing);.int sqlite
31950 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
31960 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
31970 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
31980 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
31990 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72  te3_bind_pointer
319a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
319b0 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 63 6f 6e 73  int, void*, cons
319c0 74 20 63 68 61 72 2a 2c 76 6f 69 64 28 2a 29 28  t char*,void(*)(
319d0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
319e0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
319f0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
31a00 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 69  , int, int n);.i
31a10 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
31a20 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74  zeroblob64(sqlit
31a30 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
31a40 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
31a50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31a60 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
31a70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54  arameters.** MET
31a80 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
31a90 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
31aa0 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
31ab0 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
31ac0 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72  mber of [SQL par
31ad0 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61  ameters].** in a
31ae0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31af0 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61  ment].  SQL para
31b00 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e  meters are token
31b10 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
31b20 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a   "?", "?NNN", ":
31b30 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72  AAA", "$AAA", or
31b40 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72   "@AAA" that ser
31b50 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f  ve as.** placeho
31b60 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
31b70 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
31b80 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
31b90 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
31ba0 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
31bb0 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
31bc0 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
31bd0 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
31be0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
31bf0 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
31c00 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
31c10 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
31c20 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
31c30 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
31c40 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
31c50 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
31c60 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
31c70 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
31c80 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20  e ?NNN form are 
31c90 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
31ca0 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
31cb0 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e list.)^.**.** 
31cc0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
31cd0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
31ce0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
31cf0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
31d00 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
31d10 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
31d20 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
31d30 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
31d40 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
31d50 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
31d60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
31d70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31d80 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
31d90 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48  arameter.** METH
31da0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
31db0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
31dc0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
31dd0 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74  er_name(P,N) int
31de0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
31df0 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * the name of th
31e00 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61  e N-th [SQL para
31e10 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70  meter] in the [p
31e20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31e30 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70  t] P..** ^(SQL p
31e40 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
31e50 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
31e60 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
31e70 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
31e80 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
31e90 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
31ea0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
31eb0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
31ec0 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
31ed0 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
31ee0 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
31ef0 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
31f00 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
31f10 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
31f20 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29  rt of the name.)
31f30 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73  ^.** ^Parameters
31f40 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
31f50 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
31f60 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
31f70 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64  e no name.** and
31f80 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f   are referred to
31f90 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f   as "nameless" o
31fa0 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  r "anonymous par
31fb0 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20  ameters"..**.** 
31fc0 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20  ^The first host 
31fd0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
31fe0 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74   index of 1, not
31ff0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   0..**.** ^If th
32000 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74  e value N is out
32010 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
32020 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74  the N-th paramet
32030 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
32040 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
32050 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20  returned.  ^The 
32060 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
32070 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20  is.** always in 
32080 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65  UTF-8 encoding e
32090 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64  ven if the named
320a0 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a   parameter was.*
320b0 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65  * originally spe
320c0 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36  cified as UTF-16
320d0 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   in [sqlite3_pre
320e0 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 5b 73  pare16()],.** [s
320f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
32100 5f 76 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  _v2()], or [sqli
32110 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
32120 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
32130 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
32140 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
32150 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
32160 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
32170 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
32180 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
32190 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
321a0 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  ex()]..*/.const 
321b0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69  char *sqlite3_bi
321c0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
321d0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
321e0 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
321f0 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
32200 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
32210 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a  h A Given Name.*
32220 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
32230 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  3_stmt.**.** ^Re
32240 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f  turn the index o
32250 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
32260 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  er given its nam
32270 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65  e.  ^The.** inde
32280 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  x value returned
32290 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72   is suitable for
322a0 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f   use as the seco
322b0 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  nd.** parameter 
322c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
322d0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
322e0 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a  nd()].  ^A zero.
322f0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
32300 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61  f no matching pa
32310 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64  rameter is found
32320 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
32330 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62  r.** name must b
32340 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38  e given in UTF-8
32350 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69   even if the ori
32360 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a  ginal statement.
32370 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20  ** was prepared 
32380 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74  from UTF-16 text
32390 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
323a0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
323b0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  or.** [sqlite3_p
323c0 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a  repare16_v3()]..
323d0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
323e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
323f0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
32400 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
32410 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
32420 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
32430 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
32440 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e  rameter_name()].
32450 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
32460 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
32470 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
32480 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
32490 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
324a0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
324b0 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
324c0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
324d0 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ent.** METHOD: s
324e0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
324f0 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74  * ^Contrary to t
32500 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20  he intuition of 
32510 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72  many, [sqlite3_r
32520 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74  eset()] does not
32530 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73   reset.** the [s
32540 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
32550 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20   | bindings] on 
32560 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
32570 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20  ement]..** ^Use 
32580 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
32590 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
325a0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
325b0 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
325c0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
325d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
325e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
325f0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
32600 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
32610 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  Set.** METHOD: s
32620 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
32630 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75  * ^Return the nu
32640 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
32650 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
32660 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  t returned by th
32670 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
32680 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 49 66 20 74  tatement]. ^If t
32690 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
326a0 72 6e 73 20 30 2c 20 74 68 61 74 20 6d 65 61 6e  rns 0, that mean
326b0 73 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61  s the .** [prepa
326c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 72  red statement] r
326d0 65 74 75 72 6e 73 20 6e 6f 20 64 61 74 61 20 28  eturns no data (
326e0 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b  for example an [
326f0 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e 48 6f  UPDATE])..** ^Ho
32700 77 65 76 65 72 2c 20 6a 75 73 74 20 62 65 63 61  wever, just beca
32710 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  use this routine
32720 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74   returns a posit
32730 69 76 65 20 6e 75 6d 62 65 72 20 64 6f 65 73 20  ive number does 
32740 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  not.** mean that
32750 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 72 6f 77   one or more row
32760 73 20 6f 66 20 64 61 74 61 20 77 69 6c 6c 20 62  s of data will b
32770 65 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 41 20  e returned.  ^A 
32780 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
32790 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  .** will always 
327a0 68 61 76 65 20 61 20 70 6f 73 69 74 69 76 65 20  have a positive 
327b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
327c0 6f 75 6e 74 28 29 20 62 75 74 20 64 65 70 65 6e  ount() but depen
327d0 64 69 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a 20 57  ding on the.** W
327e0 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73  HERE clause cons
327f0 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 65 20  traints and the 
32800 74 61 62 6c 65 20 63 6f 6e 74 65 6e 74 2c 20 69  table content, i
32810 74 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 6e  t might return n
32820 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 53 65  o rows..**.** Se
32830 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
32840 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a  _data_count()].*
32850 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
32860 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
32870 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
32880 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32890 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
328a0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
328b0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
328c0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
328d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
328e0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
328f0 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
32900 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
32910 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
32920 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
32930 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65  statement.  ^The
32940 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32950 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
32960 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
32970 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
32980 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
32990 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
329a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
329b0 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
329c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
329d0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
329e0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
329f0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
32a00 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72  meter is the [pr
32a10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
32a20 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d  ].** that implem
32a30 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54  ents the [SELECT
32a40 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68  ] statement. ^Th
32a50 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
32a60 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c  er is the.** col
32a70 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68  umn number.  ^Th
32a80 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
32a90 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a  n is number 0..*
32aa0 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
32ab0 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
32ac0 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
32ad0 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65   either the [pre
32ae0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
32af0 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64  .** is destroyed
32b00 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
32b10 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
32b20 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
32b30 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
32b40 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
32b50 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
32b60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
32b70 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
32b80 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
32b90 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63  until the next c
32ba0 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
32bb0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
32bc0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
32bd0 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68  n_name16() on th
32be0 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a  e same column..*
32bf0 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  *.** ^If sqlite3
32c00 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
32c10 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
32c20 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
32c30 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
32c40 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
32c50 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
32c60 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
32c70 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
32c80 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
32c90 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
32ca0 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c   name of a resul
32cb0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
32cc0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53  value of the "AS
32cd0 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20  " clause for.** 
32ce0 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20  that column, if 
32cf0 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63  there is an AS c
32d00 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65  lause.  If there
32d10 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65   is no AS clause
32d20 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d  .** then the nam
32d30 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e of the column 
32d40 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  is unspecified a
32d50 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  nd may change fr
32d60 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73  om.** one releas
32d70 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74  e of SQLite to t
32d80 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73  he next..*/.cons
32d90 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
32da0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
32db0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
32dc0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
32dd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
32de0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
32df0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
32e00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
32e10 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
32e20 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
32e30 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
32e40 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
32e50 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
32e60 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
32e70 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74  etermine the dat
32e80 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
32e90 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d  d.** table colum
32ea0 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72  n that is the or
32eb0 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63  igin of a partic
32ec0 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75  ular result colu
32ed0 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54  mn in.** [SELECT
32ee0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
32ef0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
32f00 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
32f10 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
32f20 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
32f30 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
32f40 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
32f50 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62  ng.  ^The _datab
32f60 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
32f70 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
32f80 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
32f90 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
32fa0 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
32fb0 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
32fc0 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
32fd0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
32fe0 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54  lumn name..** ^T
32ff0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
33000 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
33010 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
33020 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
33030 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
33040 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
33050 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
33060 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
33070 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
33080 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
33090 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
330a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
330b0 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
330c0 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
330d0 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
330e0 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
330f0 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
33100 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
33110 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
33120 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
33130 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
33140 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
33150 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
33160 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
33170 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
33180 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
33190 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74  ent to these int
331a0 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72  erfaces is a [pr
331b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
331c0 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  ]..** ^These fun
331d0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
331e0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
331f0 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
33200 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
33210 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
33220 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
33230 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
33240 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  on argument..** 
33250 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
33260 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20  olumn is column 
33270 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  0 for these rout
33280 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ines..**.** ^If 
33290 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
332a0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
332b0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
332c0 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
332d0 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
332e0 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
332f0 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
33300 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
33310 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
33320 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20   ^These routine 
33330 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
33340 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
33350 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
33360 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
33370 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79  ^Otherwise, they
33380 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
33390 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
333a0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
333b0 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74  ,.** or column t
333c0 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
333d0 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
333e0 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
333f0 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  * ^As with all o
33400 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
33410 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61  , those whose na
33420 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36  mes end with "16
33430 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
33440 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
33450 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  gs and the other
33460 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
33470 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e  n UTF-8..**.** ^
33480 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
33490 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
334a0 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
334b0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
334c0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
334d0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
334e0 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
334f0 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a  ssor symbol..**.
33500 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
33510 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
33520 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
33530 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
33540 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
33550 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
33560 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
33570 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
33580 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
33590 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
335a0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
335b0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
335c0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
335d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
335e0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
335f0 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
33600 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
33610 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
33620 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
33630 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
33640 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
33650 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
33660 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
33670 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f  undefined..*/.co
33680 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
33690 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
336a0 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
336b0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
336c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
336d0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
336e0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
336f0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
33700 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
33710 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
33720 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
33730 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
33740 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
33750 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
33760 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
33770 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
33780 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
33790 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
337a0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
337b0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
337c0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
337d0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
337e0 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
337f0 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
33800 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
33810 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20  Query Result.** 
33820 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
33830 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  stmt.**.** ^(The
33840 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
33850 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
33860 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49  statement]..** I
33870 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74  f this statement
33880 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   is a [SELECT] s
33890 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65  tatement and the
338a0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
338b0 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72  he.** returned r
338c0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61  esult set of tha
338d0 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20  t [SELECT] is a 
338e0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f  table column (no
338f0 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  t an.** expressi
33900 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20  on or subquery) 
33910 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65  then the declare
33920 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61  d type of the ta
33930 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73  ble.** column is
33940 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49   returned.)^  ^I
33950 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
33960 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
33970 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72  et is an.** expr
33980 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
33990 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20  ry, then a NULL 
339a0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
339b0 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ned..** ^The ret
339c0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
339d0 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63  always UTF-8 enc
339e0 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f  oded..**.** ^(Fo
339f0 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e  r example, given
33a00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
33a10 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41  hema:.**.** CREA
33a20 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56  TE TABLE t1(c1 V
33a30 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61  ARIANT);.**.** a
33a40 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
33a50 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
33a60 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a   compiled:.**.**
33a70 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20   SELECT c1 + 1, 
33a80 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a  c1 FROM t1;.**.*
33a90 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  * this routine w
33aa0 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
33ab0 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22  string "VARIANT"
33ac0 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20   for the second 
33ad0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e  result.** column
33ae0 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e   (i==1), and a N
33af0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
33b00 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74  the first result
33b10 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29   column (i==0).)
33b20 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
33b30 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e  uses dynamic run
33b40 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e  -time typing.  ^
33b50 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
33b60 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
33b70 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
33b80 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
33b90 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
33ba0 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
33bb0 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
33bc0 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
33bd0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
33be0 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
33bf0 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
33c00 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
33c10 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
33c20 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a  tatic.  ^Type.**
33c30 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
33c40 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76  ith individual v
33c50 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20  alues, not with 
33c60 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a  the containers.*
33c70 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
33c80 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a  hose values..*/.
33c90 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
33ca0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
33cb0 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
33cc0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
33cd0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
33ce0 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71  mn_decltype16(sq
33cf0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
33d00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33d10 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53  F: Evaluate An S
33d20 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
33d30 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
33d40 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  stmt.**.** After
33d50 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
33d60 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
33d70 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
33d80 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  any of.** [sqlit
33d90 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
33da0 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
33db0 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v3()], [sqlit
33dc0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
33dd0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
33de0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
33df0 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
33e00 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
33e10 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
33e20 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
33e30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
33e40 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
33e50 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
33e60 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
33e70 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
33e80 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
33e90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
33ea0 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
33eb0 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
33ec0 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
33ed0 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
33ee0 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
33ef0 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
33f00 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
33f10 65 72 20 22 76 58 22 20 69 6e 74 65 72 66 61 63  er "vX" interfac
33f20 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  es.** [sqlite3_p
33f30 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73  repare_v3()], [s
33f40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
33f50 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70  2()], [sqlite3_p
33f60 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2c 0a  repare16_v3()],.
33f70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
33f80 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
33f90 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
33fa0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
33fb0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
33fc0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
33fd0 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68  repare16()].  Th
33fe0 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20  e use of the.** 
33ff0 6e 65 77 20 22 76 58 22 20 69 6e 74 65 72 66 61  new "vX" interfa
34000 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
34010 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63  d for new applic
34020 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c  ations but the l
34030 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
34040 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  ce will continue
34050 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
34060 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ..**.** ^In the 
34070 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
34080 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
34090 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
340a0 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
340b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
340c0 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
340d0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
340e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
340f0 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  SE]..** ^With th
34100 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
34110 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
34120 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
34130 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
34140 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
34150 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
34160 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
34170 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20   ^[SQLITE_BUSY] 
34180 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
34190 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
341a0 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
341b0 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
341c0 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
341d0 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
341e0 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74  b.  ^If the stat
341f0 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
34200 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
34210 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
34220 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
34230 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
34240 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
34250 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
34260 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
34270 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
34280 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
34290 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74  an.** explicit t
342a0 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
342b0 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
342c0 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
342d0 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
342e0 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
342f0 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d  ^[SQLITE_DONE] m
34300 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
34310 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
34320 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
34330 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
34340 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
34350 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
34360 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
34370 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
34380 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
34390 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
343a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
343b0 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
343c0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
343d0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
343e0 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  l state..**.** ^
343f0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
34400 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
34410 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
34420 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
34430 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
34440 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
34450 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
34460 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
34470 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
34480 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
34490 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
344a0 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
344b0 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
344c0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
344d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
344e0 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
344f0 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
34500 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
34510 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
34520 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
34530 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
34540 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
34550 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
34560 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
34570 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
34580 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
34590 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
345a0 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
345b0 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
345c0 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
345d0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
345e0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57  errmsg()]..** ^W
345f0 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
34600 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
34610 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
34620 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
34630 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
34640 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
34650 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
34660 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
34670 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
34680 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
34690 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
346a0 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
346b0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
346c0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20  tatement].  ^In 
346d0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
346e0 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
346f0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
34700 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
34710 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
34720 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
34730 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
34740 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
34750 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
34760 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
34770 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
34780 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
34790 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
347a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
347b0 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
347c0 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
347d0 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
347e0 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
347f0 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
34800 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
34810 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
34820 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
34830 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
34840 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
34850 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
34860 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
34870 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
34880 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
34890 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
348a0 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
348b0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20  ..**.** For all 
348c0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
348d0 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63  te up to and inc
348e0 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c  luding 3.6.23.1,
348f0 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
34900 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
34910 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74  was required aft
34920 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  er sqlite3_step(
34930 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68  ) returned anyth
34940 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61  ing.** other tha
34950 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62  n [SQLITE_ROW] b
34960 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71  efore any subseq
34970 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  uent invocation 
34980 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  of.** sqlite3_st
34990 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74  ep().  Failure t
349a0 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  o reset the prep
349b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
349c0 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
349d0 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64  3_reset()] would
349e0 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53   result in an [S
349f0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65  QLITE_MISUSE] re
34a00 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  turn from.** sql
34a10 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75  ite3_step().  Bu
34a20 74 20 61 66 74 65 72 20 5b 76 65 72 73 69 6f 6e  t after [version
34a30 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b 64 61 74   3.6.23.1] ([dat
34a40 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a 2a  eof:3.6.23.1],.*
34a50 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
34a60 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e   began.** callin
34a70 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
34a80 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ()] automaticall
34a90 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d  y in this circum
34aa0 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a  stance rather.**
34ab0 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20   than returning 
34ac0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
34ad0 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f    This is not co
34ae0 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61  nsidered a compa
34af0 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61  tibility.** brea
34b00 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70  k because any ap
34b10 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65  plication that e
34b20 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20  ver receives an 
34b30 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72  SQLITE_MISUSE er
34b40 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e  ror.** is broken
34b50 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   by definition. 
34b60 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   The [SQLITE_OMI
34b70 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d  T_AUTORESET] com
34b80 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
34b90 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20  .** can be used 
34ba0 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c  to restore the l
34bb0 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a  egacy behavior..
34bc0 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
34bd0 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
34be0 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63  /b> In the legac
34bf0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
34c00 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a   sqlite3_step().
34c10 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65  ** API always re
34c20 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20  turns a generic 
34c30 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c  error code, [SQL
34c40 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c  ITE_ERROR], foll
34c50 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72  owing any.** err
34c60 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  or other than [S
34c70 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20  QLITE_BUSY] and 
34c80 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
34c90 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a    You must call.
34ca0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
34cb0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
34cc0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20  _finalize()] in 
34cd0 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e  order to find on
34ce0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63  e of the.** spec
34cf0 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
34d00 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64  s] that better d
34d10 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
34d20 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20  or..** We admit 
34d30 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67  that this is a g
34d40 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68  oofy design.  Th
34d50 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65  e problem has be
34d60 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68  en fixed.** with
34d70 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
34d80 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65  ace.  If you pre
34d90 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72  pare all of your
34da0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
34db0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
34dc0 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20  3_prepare_v3()] 
34dd0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
34de0 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72 20  are_v2()].** or 
34df0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
34e00 31 36 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  16_v2()] or [sql
34e10 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
34e20 33 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20  3()] instead.** 
34e30 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  of the legacy [s
34e40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
34e50 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
34e60 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65  repare16()] inte
34e70 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20  rfaces,.** then 
34e80 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
34e90 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
34ea0 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
34eb0 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
34ec0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
34ed0 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 58 22   use of the "vX"
34ee0 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 72   interfaces is r
34ef0 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69  ecommended..*/.i
34f00 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  nt sqlite3_step(
34f10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
34f20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34f30 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   Number of colum
34f40 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73  ns in a result s
34f50 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
34f60 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
34f70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
34f80 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65  ta_count(P) inte
34f90 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
34fa0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
34fb0 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75  mns in the.** cu
34fc0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
34fd0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b   result set of [
34fe0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34ff0 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72  nt] P..** ^If pr
35000 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
35010 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65   P does not have
35020 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74   results ready t
35030 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61  o return.** (via
35040 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73   calls to the [s
35050 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
35060 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t | sqlite3_colu
35070 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e  mn_*()] of.** in
35080 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73  terfaces) then s
35090 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
350a0 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a  t(P) returns 0..
350b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
350c0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
350d0 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72  utine also retur
350e0 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e  ns 0 if P is a N
350f0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ULL pointer..** 
35100 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
35110 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
35120 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
35130 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
35140 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
35150 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
35160 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ed [SQLITE_DONE]
35170 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
35180 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a  data_count(P).**
35190 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e   will return non
351a0 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75  -zero if previou
351b0 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  s call to [sqlit
351c0 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
351d0 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
351e0 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20  ROW], except in 
351f0 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20  the case of the 
35200 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e  [PRAGMA incremen
35210 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77  tal_vacuum].** w
35220 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72  here it always r
35230 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63  eturns zero sinc
35240 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74  e each step of t
35250 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a  hat multi-step.*
35260 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73  * pragma returns
35270 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61   0 columns of da
35280 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ta..**.** See al
35290 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  so: [sqlite3_col
352a0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  umn_count()].*/.
352b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
352c0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
352d0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
352e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
352f0 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
35300 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
35310 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
35320 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65  ** ^(Every value
35330 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f   in SQLite has o
35340 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61  ne of five funda
35350 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73  mental datatypes
35360 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
35370 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e  <li> 64-bit sign
35380 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c  ed integer.** <l
35390 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66  i> 64-bit IEEE f
353a0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
353b0 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72  mber.** <li> str
353c0 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42  ing.** <li> BLOB
353d0 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a  .** <li> NULL.**
353e0 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
353f0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
35400 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
35410 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
35420 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
35430 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
35440 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
35450 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
35460 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
35470 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
35480 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
35490 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
354a0 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
354b0 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
354c0 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
354d0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
354e0 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
354f0 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53  3_TEXT, not.** S
35500 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
35510 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
35520 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
35530 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
35540 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
35550 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
35560 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
35570 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
35580 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
35590 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
355a0 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
355b0 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
355c0 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
355d0 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
355e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
355f0 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20  : Result Values 
35600 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20  From A Query.** 
35610 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
35620 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
35630 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ns}.** METHOD: s
35640 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
35650 2a 20 3c 62 3e 53 75 6d 6d 61 72 79 3a 3c 2f 62  * <b>Summary:</b
35660 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  >.** <blockquote
35670 3e 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 30  ><table border=0
35680 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 30 20 63   cellpadding=0 c
35690 65 6c 6c 73 70 61 63 69 6e 67 3d 30 3e 0a 2a 2a  ellspacing=0>.**
356a0 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
356b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 3c  te3_column_blob<
356c0 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
356d0 3e 42 4c 4f 42 20 72 65 73 75 6c 74 0a 2a 2a 20  >BLOB result.** 
356e0 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
356f0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
35700 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
35710 64 3e 52 45 41 4c 20 72 65 73 75 6c 74 0a 2a 2a  d>REAL result.**
35720 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
35730 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 3c 2f  te3_column_int</
35740 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
35750 33 32 2d 62 69 74 20 49 4e 54 45 47 45 52 20 72  32-bit INTEGER r
35760 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  esult.** <tr><td
35770 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ><b>sqlite3_colu
35780 6d 6e 5f 69 6e 74 36 34 3c 2f 62 3e 3c 74 64 3e  mn_int64</b><td>
35790 26 72 61 72 72 3b 3c 74 64 3e 36 34 2d 62 69 74  &rarr;<td>64-bit
357a0 20 49 4e 54 45 47 45 52 20 72 65 73 75 6c 74 0a   INTEGER result.
357b0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
357c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
357d0 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  t</b><td>&rarr;<
357e0 74 64 3e 55 54 46 2d 38 20 54 45 58 54 20 72 65  td>UTF-8 TEXT re
357f0 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  sult.** <tr><td>
35800 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
35810 6e 5f 74 65 78 74 31 36 3c 2f 62 3e 3c 74 64 3e  n_text16</b><td>
35820 26 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d 31 36  &rarr;<td>UTF-16
35830 20 54 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20   TEXT result.** 
35840 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
35850 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 3c  e3_column_value<
35860 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
35870 3e 54 68 65 20 72 65 73 75 6c 74 20 61 73 20 61  >The result as a
35880 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  n .** [sqlite3_v
35890 61 6c 75 65 7c 75 6e 70 72 6f 74 65 63 74 65 64  alue|unprotected
358a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
358b0 6f 62 6a 65 63 74 2e 0a 2a 2a 20 3c 74 72 3e 3c  object..** <tr><
358c0 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62  td>&nbsp;<td>&nb
358d0 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 0a 2a 2a  sp;<td>&nbsp;.**
358e0 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
358f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
35900 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
35910 64 3e 53 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42  d>Size of a BLOB
35920 0a 2a 2a 20 6f 72 20 61 20 55 54 46 2d 38 20 54  .** or a UTF-8 T
35930 45 58 54 20 72 65 73 75 6c 74 20 69 6e 20 62 79  EXT result in by
35940 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  tes.** <tr><td><
35950 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
35960 5f 62 79 74 65 73 31 36 26 6e 62 73 70 3b 26 6e  _bytes16&nbsp;&n
35970 62 73 70 3b 3c 2f 62 3e 0a 2a 2a 20 3c 74 64 3e  bsp;</b>.** <td>
35980 26 72 61 72 72 3b 26 6e 62 73 70 3b 26 6e 62 73  &rarr;&nbsp;&nbs
35990 70 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 55 54  p;<td>Size of UT
359a0 46 2d 31 36 0a 2a 2a 20 54 45 58 54 20 69 6e 20  F-16.** TEXT in 
359b0 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64  bytes.** <tr><td
359c0 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ><b>sqlite3_colu
359d0 6d 6e 5f 74 79 70 65 3c 2f 62 3e 3c 74 64 3e 26  mn_type</b><td>&
359e0 72 61 72 72 3b 3c 74 64 3e 44 65 66 61 75 6c 74  rarr;<td>Default
359f0 0a 2a 2a 20 64 61 74 61 74 79 70 65 20 6f 66 20  .** datatype of 
35a00 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 2f  the result.** </
35a10 74 61 62 6c 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  table></blockquo
35a20 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 44 65 74  te>.**.** <b>Det
35a30 61 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20  ails:</b>.**.** 
35a40 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
35a50 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
35a60 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c  on about a singl
35a70 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
35a80 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c  current.** resul
35a90 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
35aa0 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73  .  ^In every cas
35ab0 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
35ac0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
35ad0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
35ae0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
35af0 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
35b00 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
35b10 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
35b20 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
35b30 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
35b40 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
35b50 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
35b60 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
35b70 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
35b80 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
35b90 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
35ba0 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
35bb0 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
35bc0 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c  returned. ^The l
35bd0 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
35be0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
35bf0 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
35c00 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72  ..** ^The number
35c10 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
35c20 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65  he result can be
35c30 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e   determined usin
35c40 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  g.** [sqlite3_co
35c50 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a  lumn_count()]..*
35c60 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
35c70 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
35c80 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
35c90 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
35ca0 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
35cb0 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20  column index is 
35cc0 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
35cd0 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  e result is unde
35ce0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20  fined..** These 
35cf0 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
35d00 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
35d10 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
35d20 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
35d30 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
35d40 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
35d50 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
35d60 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
35d70 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
35d80 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
35d90 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
35da0 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  d subsequently..
35db0 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
35dc0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
35dd0 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
35de0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
35df0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
35e00 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
35e10 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
35e20 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
35e30 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
35e40 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
35e50 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
35e60 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
35e70 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
35e80 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
35e90 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
35ea0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
35eb0 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
35ec0 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
35ed0 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
35ee0 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
35ef0 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
35f00 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
35f10 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
35f20 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
35f30 65 20 66 69 72 73 74 20 73 69 78 20 69 6e 74 65  e first six inte
35f40 72 66 61 63 65 73 20 28 5f 62 6c 6f 62 2c 20 5f  rfaces (_blob, _
35f50 64 6f 75 62 6c 65 2c 20 5f 69 6e 74 2c 20 5f 69  double, _int, _i
35f60 6e 74 36 34 2c 20 5f 74 65 78 74 2c 20 61 6e 64  nt64, _text, and
35f70 20 5f 74 65 78 74 31 36 29 0a 2a 2a 20 65 61 63   _text16).** eac
35f80 68 20 72 65 74 75 72 6e 20 74 68 65 20 76 61 6c  h return the val
35f90 75 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63  ue of a result c
35fa0 6f 6c 75 6d 6e 20 69 6e 20 61 20 73 70 65 63 69  olumn in a speci
35fb0 66 69 63 20 64 61 74 61 20 66 6f 72 6d 61 74 2e  fic data format.
35fc0 20 20 49 66 0a 2a 2a 20 74 68 65 20 72 65 73 75    If.** the resu
35fd0 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 6f 74  lt column is not
35fe0 20 69 6e 69 74 69 61 6c 6c 79 20 69 6e 20 74 68   initially in th
35ff0 65 20 72 65 71 75 65 73 74 65 64 20 66 6f 72 6d  e requested form
36000 61 74 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c  at (for example,
36010 0a 2a 2a 20 69 66 20 74 68 65 20 71 75 65 72 79  .** if the query
36020 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
36030 67 65 72 20 62 75 74 20 74 68 65 20 73 71 6c 69  ger but the sqli
36040 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
36050 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  ) interface.** i
36060 73 20 75 73 65 64 20 74 6f 20 65 78 74 72 61 63  s used to extrac
36070 74 20 74 68 65 20 76 61 6c 75 65 29 20 74 68 65  t the value) the
36080 6e 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 74  n an automatic t
36090 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ype conversion i
360a0 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a  s performed..**.
360b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
360c0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
360d0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
360e0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e.** [SQLITE_INT
360f0 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20  EGER | datatype 
36100 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e  code] for the in
36110 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a  itial data type.
36120 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
36130 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72   column.  ^The r
36140 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
36150 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
36160 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
36170 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
36180 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
36190 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
361a0 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 0a 2a 2a 20  QLITE_NULL]..** 
361b0 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
361c0 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
361d0 6d 6e 5f 74 79 70 65 28 29 20 63 61 6e 20 62 65  mn_type() can be
361e0 20 75 73 65 64 20 74 6f 20 64 65 63 69 64 65 20   used to decide 
361f0 77 68 69 63 68 0a 2a 2a 20 6f 66 20 74 68 65 20  which.** of the 
36200 66 69 72 73 74 20 73 69 78 20 69 6e 74 65 72 66  first six interf
36210 61 63 65 20 73 68 6f 75 6c 64 20 62 65 20 75 73  ace should be us
36220 65 64 20 74 6f 20 65 78 74 72 61 63 74 20 74 68  ed to extract th
36230 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e 0a  e column value..
36240 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74  ** The value ret
36250 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
36260 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
36270 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
36280 6c 20 69 66 20 6e 6f 0a 2a 2a 20 61 75 74 6f 6d  l if no.** autom
36290 61 74 69 63 20 74 79 70 65 20 63 6f 6e 76 65 72  atic type conver
362a0 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
362b0 72 65 64 20 66 6f 72 20 74 68 65 20 76 61 6c 75  red for the valu
362c0 65 20 69 6e 20 71 75 65 73 74 69 6f 6e 2e 20 20  e in question.  
362d0 0a 2a 2a 20 41 66 74 65 72 20 61 20 74 79 70 65  .** After a type
362e0 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 20 74 68 65   conversion, the
362f0 20 72 65 73 75 6c 74 20 6f 66 20 63 61 6c 6c 69   result of calli
36300 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ng sqlite3_colum
36310 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 69 73 20 75  n_type().** is u
36320 6e 64 65 66 69 6e 65 64 2c 20 74 68 6f 75 67 68  ndefined, though
36330 20 68 61 72 6d 6c 65 73 73 2e 20 20 46 75 74 75   harmless.  Futu
36340 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
36350 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
36360 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
36370 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
36380 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
36390 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
363a0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
363b0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
363c0 20 61 20 42 4c 4f 42 20 6f 72 20 61 20 54 45 58   a BLOB or a TEX
363d0 54 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 74  T string, then t
363e0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
363f0 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 6f 72 20  n_bytes().** or 
36400 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36410 79 74 65 73 31 36 28 29 20 69 6e 74 65 72 66 61  ytes16() interfa
36420 63 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  ces can be used 
36430 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  to determine the
36440 20 73 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 61 74   size.** of that
36450 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
36460 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
36470 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
36480 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
36490 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
364a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
364b0 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
364c0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
364d0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
364e0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
364f0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
36500 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
36510 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
36520 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
36530 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
36540 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
36550 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
36560 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
36570 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
36580 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
36590 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
365a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
365b0 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
365c0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
365d0 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
365e0 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
365f0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
36600 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
36610 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
36620 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
36630 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
36640 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
36650 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36660 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a  ytes() returns z
36670 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ero..**.** ^If t
36680 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
36690 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74  LOB or UTF-16 st
366a0 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
366b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
366c0 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  es16().** routin
366d0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
366e0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
366f0 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
36700 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
36710 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
36720 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  -8 string, then 
36730 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36740 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74  ytes16() convert
36750 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
36760 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68  to UTF-16 and th
36770 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
36780 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
36790 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
367a0 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
367b0 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
367c0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
367d0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
367e0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
367f0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
36800 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31  value to a UTF-1
36810 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  6 string and ret
36820 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
36830 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
36840 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
36850 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
36860 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
36870 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
36880 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  16() returns zer
36890 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61  o..**.** ^The va
368a0 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
368b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
368c0 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a  _bytes()] and .*
368d0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
368e0 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20  n_bytes16()] do 
368f0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
36900 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73  zero terminators
36910 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
36920 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e  f the string.  ^
36930 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
36940 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
36950 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
36960 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
36970 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
36980 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61  umn_bytes16()] a
36990 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  re the number of
369a0 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
369b0 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
369c0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
369d0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74  cters..**.** ^St
369e0 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
369f0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
36a00 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
36a10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
36a20 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
36a30 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
36a40 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
36a50 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65  inated.  ^The re
36a60 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
36a70 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
36a80 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
36a90 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
36aa0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
36ab0 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e  r..**.** <b>Warn
36ac0 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62  ing:</b> ^The ob
36ad0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
36ae0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
36af0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
36b00 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
36b10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
36b20 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c  bject.  In a mul
36b30 74 69 74 68 72 65 61 64 65 64 20 65 6e 76 69 72  tithreaded envir
36b40 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e  onment,.** an un
36b50 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
36b60 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
36b70 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
36b80 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b  safely with.** [
36b90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
36ba0 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
36bb0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
36bc0 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75  )]..** If the [u
36bd0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
36be0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
36bf0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
36c00 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
36c10 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64  value()] is used
36c20 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61   in any other wa
36c30 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c  y, including cal
36c40 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65  ls.** to routine
36c50 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
36c60 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73  value_int()], [s
36c70 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
36c80 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
36c90 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
36ca0 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f  ()], the behavio
36cb0 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  r is not threads
36cc0 61 66 65 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 74  afe..** Hence, t
36cd0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
36ce0 6e 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  n_value() interf
36cf0 61 63 65 0a 2a 2a 20 69 73 20 6e 6f 72 6d 61 6c  ace.** is normal
36d00 6c 79 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 77  ly only useful w
36d10 69 74 68 69 6e 20 74 68 65 20 69 6d 70 6c 65 6d  ithin the implem
36d20 65 6e 74 61 74 69 6f 6e 20 6f 66 20 0a 2a 2a 20  entation of .** 
36d30 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
36d40 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
36d50 6e 73 5d 20 6f 72 20 5b 76 69 72 74 75 61 6c 20  ns] or [virtual 
36d60 74 61 62 6c 65 73 5d 2c 20 6e 6f 74 20 77 69 74  tables], not wit
36d70 68 69 6e 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  hin.** top-level
36d80 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
36d90 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 65  e..**.** The the
36da0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
36db0 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
36dc0 72 74 20 74 68 65 20 64 61 74 61 74 79 70 65 20  rt the datatype 
36dd0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  of the result..*
36de0 2a 20 5e 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  * ^For example, 
36df0 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  if the internal 
36e00 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69  representation i
36e10 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65  s FLOAT and a te
36e20 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  xt result.** is 
36e30 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69  requested, [sqli
36e40 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
36e50 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
36e60 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68  ly to perform th
36e70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e.** conversion 
36e80 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
36e90 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  ^(The following 
36ea0 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68  table details th
36eb0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a  e conversions.**
36ec0 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65   that are applie
36ed0 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d:.**.** <blockq
36ee0 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
36ef0 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
36f00 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c  tr><th> Internal
36f10 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65  <br>Type <th> Re
36f20 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20  quested<br>Type 
36f30 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e  <th>  Conversion
36f40 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
36f50 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e   NULL    <td> IN
36f60 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73  TEGER   <td> Res
36f70 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e  ult is 0.** <tr>
36f80 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
36f90 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
36fa0 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a  > Result is 0.0.
36fb0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
36fc0 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  L    <td>   TEXT
36fd0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
36fe0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
36ff0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
37000 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
37010 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
37020 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
37030 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
37040 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46  INTEGER  <td>  F
37050 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
37060 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65  vert from intege
37070 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74  r to float.** <t
37080 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
37090 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
370a0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
370b0 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67  ing of the integ
370c0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
370d0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42  NTEGER  <td>   B
370e0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
370f0 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58   as INTEGER->TEX
37100 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  T.** <tr><td>  F
37110 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOAT   <td> INTE
37120 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
37130 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
37140 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
37150 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
37160 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
37170 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
37180 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
37190 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
371a0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  LOB    <td> [CAS
371b0 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74  T] to BLOB.** <t
371c0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
371d0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
371e0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
371f0 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
37200 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
37210 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b   FLOAT    <td> [
37220 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a  CAST] to REAL.**
37230 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
37240 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
37250 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
37260 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
37270 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
37280 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
37290 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
372a0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
372b0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
372c0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52  <td> [CAST] to R
372d0 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EAL.** <tr><td> 
372e0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
372f0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
37300 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
37310 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
37320 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
37330 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
37340 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
37350 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
37360 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
37370 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
37380 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
37390 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
373a0 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
373b0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
373c0 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
373d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
373e0 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
373f0 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76  ed..** Type conv
37400 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
37410 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
37420 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
37430 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
37440 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
37450 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
37460 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
37470 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
37480 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
37490 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  t() or.**      s
374a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
374b0 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
374c0 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
374d0 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
374e0 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
374f0 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
37500 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  g.</li>.** <li> 
37510 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
37520 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
37530 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
37540 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
37550 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
37560 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
37570 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
37580 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
37590 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
375a0 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
375b0 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
375c0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
375d0 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
375e0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
375f0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
37600 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
37610 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
37620 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
37630 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
37640 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
37650 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  UTF-8.</li>.** <
37660 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76  /ul>.**.** ^Conv
37670 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
37680 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
37690 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
376a0 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
376b0 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
376c0 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
376d0 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
376e0 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
376f0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
37700 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
37710 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65  prior pointer re
37720 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61  ferences will ha
37730 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
37740 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
37750 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
37760 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
37770 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
37780 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
37790 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
377a0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
377b0 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
377c0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
377d0 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
377e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
377f0 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  t policy is to i
37800 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
37810 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
37820 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
37830 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
37840 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
37850 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
37860 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
37870 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
37880 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
37890 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
378a0 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
378b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
378c0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
378d0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
378e0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
378f0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
37900 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
37910 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
37920 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
37930 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
37940 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
37950 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
37960 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
37970 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
37980 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
37990 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
379a0 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
379b0 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
379c0 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
379d0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
379e0 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
379f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
37a00 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
37a10 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
37a20 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
37a30 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
37a40 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
37a50 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
37a60 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
37a70 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
37a80 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
37a90 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
37aa0 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
37ab0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
37ac0 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
37ad0 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
37ae0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
37af0 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s()..**.** ^The 
37b00 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
37b10 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
37b20 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
37b30 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
37b40 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
37b50 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
37b60 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
37b70 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
37b80 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
37b90 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
37ba0 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d  alled.  ^The mem
37bb0 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
37bc0 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
37bd0 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66  * and BLOBs is f
37be0 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
37bf0 6c 79 2e 20 20 44 6f 20 6e 6f 74 20 70 61 73 73  ly.  Do not pass
37c00 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
37c10 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
37c20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
37c30 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
37c40 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
37c50 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
37c60 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
37c70 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73  **.** As long as
37c80 20 74 68 65 20 69 6e 70 75 74 20 70 61 72 61 6d   the input param
37c90 65 74 65 72 73 20 61 72 65 20 63 6f 72 72 65 63  eters are correc
37ca0 74 2c 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  t, these routine
37cb0 73 20 77 69 6c 6c 20 6f 6e 6c 79 0a 2a 2a 20 66  s will only.** f
37cc0 61 69 6c 20 69 66 20 61 6e 20 6f 75 74 2d 6f 66  ail if an out-of
37cd0 2d 6d 65 6d 6f 72 79 20 65 72 72 6f 72 20 6f 63  -memory error oc
37ce0 63 75 72 73 20 64 75 72 69 6e 67 20 61 20 66 6f  curs during a fo
37cf0 72 6d 61 74 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  rmat conversion.
37d00 0a 2a 2a 20 4f 6e 6c 79 20 74 68 65 20 66 6f 6c  .** Only the fol
37d10 6c 6f 77 69 6e 67 20 73 75 62 73 65 74 20 6f 66  lowing subset of
37d20 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
37d30 73 75 62 6a 65 63 74 20 74 6f 20 6f 75 74 2d 6f  subject to out-o
37d40 66 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 65 72 72 6f  f-memory.** erro
37d50 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  rs:.**.** <ul>.*
37d60 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 63  * <li> sqlite3_c
37d70 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 0a 2a 2a 20  olumn_blob().** 
37d80 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  <li> sqlite3_col
37d90 75 6d 6e 5f 74 65 78 74 28 29 0a 2a 2a 20 3c 6c  umn_text().** <l
37da0 69 3e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  i> sqlite3_colum
37db0 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 3c 6c  n_text16().** <l
37dc0 69 3e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  i> sqlite3_colum
37dd0 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 3c 6c 69  n_bytes().** <li
37de0 3e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  > sqlite3_column
37df0 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 3c 2f  _bytes16().** </
37e00 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ul>.**.** If an 
37e10 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 65 72  out-of-memory er
37e20 72 6f 72 20 6f 63 63 75 72 73 2c 20 74 68 65 6e  ror occurs, then
37e30 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
37e40 65 20 66 72 6f 6d 20 74 68 65 73 65 0a 2a 2a 20  e from these.** 
37e50 72 6f 75 74 69 6e 65 73 20 69 73 20 74 68 65 20  routines is the 
37e60 73 61 6d 65 20 61 73 20 69 66 20 74 68 65 20 63  same as if the c
37e70 6f 6c 75 6d 6e 20 68 61 64 20 63 6f 6e 74 61 69  olumn had contai
37e80 6e 65 64 20 61 6e 20 53 51 4c 20 4e 55 4c 4c 20  ned an SQL NULL 
37e90 76 61 6c 75 65 2e 0a 2a 2a 20 56 61 6c 69 64 20  value..** Valid 
37ea0 53 51 4c 20 4e 55 4c 4c 20 72 65 74 75 72 6e 73  SQL NULL returns
37eb0 20 63 61 6e 20 62 65 20 64 69 73 74 69 6e 67 75   can be distingu
37ec0 69 73 68 65 64 20 66 72 6f 6d 20 6f 75 74 2d 6f  ished from out-o
37ed0 66 2d 6d 65 6d 6f 72 79 20 65 72 72 6f 72 73 0a  f-memory errors.
37ee0 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 74  ** by invoking t
37ef0 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  he [sqlite3_errc
37f00 6f 64 65 28 29 5d 20 69 6d 6d 65 64 69 61 74 65  ode()] immediate
37f10 6c 79 20 61 66 74 65 72 20 74 68 65 20 73 75 73  ly after the sus
37f20 70 65 63 74 0a 2a 2a 20 72 65 74 75 72 6e 20 76  pect.** return v
37f30 61 6c 75 65 20 69 73 20 6f 62 74 61 69 6e 65 64  alue is obtained
37f40 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 0a   and before any.
37f50 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ** other SQLite 
37f60 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
37f70 6c 65 64 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  led on the same 
37f80 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
37f90 74 69 6f 6e 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  tion]..*/.const 
37fa0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
37fb0 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
37fc0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
37fd0 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  l);.double sqlit
37fe0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
37ff0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
38000 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
38010 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
38020 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
38030 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
38040 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
38050 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73  3_column_int64(s
38060 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
38070 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75  t iCol);.const u
38080 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
38090 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
380a0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
380b0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
380c0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
380d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71  column_text16(sq
380e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
380f0 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
38100 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63  value *sqlite3_c
38110 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69  olumn_value(sqli
38120 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
38130 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
38140 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73  3_column_bytes(s
38150 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
38160 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
38170 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
38180 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  s16(sqlite3_stmt
38190 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
381a0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
381b0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
381c0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
381d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
381e0 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
381f0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
38200 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54  ject.** DESTRUCT
38210 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OR: sqlite3_stmt
38220 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
38230 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
38240 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
38250 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
38260 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
38270 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  t]..** ^If the m
38280 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
38290 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ation of the sta
382a0 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72  tement encounter
382b0 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  ed no errors.** 
382c0 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d  or if the statem
382d0 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65  ent is never bee
382e0 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65  n evaluated, the
382f0 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  n sqlite3_finali
38300 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  ze() returns.** 
38310 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20  SQLITE_OK.  ^If 
38320 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
38330 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74  evaluation of st
38340 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64  atement S failed
38350 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
38360 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65  3_finalize(S) re
38370 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70  turns the approp
38380 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
38390 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
383a0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  ed error code]..
383b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
383c0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
383d0 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
383e0 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
383f0 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20  t during.** the 
38400 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70  life cycle of [p
38410 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
38420 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20  t] S:.** before 
38430 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65  statement S is e
38440 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61  ver evaluated, a
38450 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d  fter.** one or m
38460 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ore calls to [sq
38470 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20  lite3_reset()], 
38480 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c  or after any cal
38490 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  l.** to [sqlite3
384a0 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c  _step()] regardl
384b0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
384c0 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d  r not the statem
384d0 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c  ent has.** compl
384e0 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a  eted execution..
384f0 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20  **.** ^Invoking 
38500 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
38510 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  () on a NULL poi
38520 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65  nter is a harmle
38530 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
38540 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
38550 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76  must finalize ev
38560 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74  ery [prepared st
38570 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65  atement] in orde
38580 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65  r to avoid.** re
38590 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49  source leaks.  I
385a0 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20  t is a grievous 
385b0 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70  error for the ap
385c0 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79  plication to try
385d0 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65   to use.** a pre
385e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
385f0 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
38600 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e  n finalized.  An
38610 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61  y use of a prepa
38620 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
38630 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
38640 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e  en finalized can
38650 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
38660 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65  ined and.** unde
38670 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
38680 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c   such as segfaul
38690 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72  ts and heap corr
386a0 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  uption..*/.int s
386b0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
386c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
386d0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
386e0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
386f0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
38700 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48  t Object.** METH
38710 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
38720 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
38730 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
38740 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
38750 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72   reset a [prepar
38760 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
38770 20 6f 62 6a 65