/ Hex Artifact Content
Login

Artifact c6bba28018378b6b43fcf4db7e9f1a3e84b0157ff54dc22ed3977acdac88e051:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c  ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a  ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66  .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53  _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f   file.  ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72  us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20  s might include 
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70  nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76  lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65  erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20  atch the macros 
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72  in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72  , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69  e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d  cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68  piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20  ing library and 
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a  header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28  <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51  ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65  ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30  ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c  BER].  ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20  rocessor macro. 
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74   Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73  e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f  ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67  py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74  amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61  he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68  racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20  e hash might be 
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b  different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6c 73 65 0a 23 20 64  nt N);.#else.# d
1e00: 65 66 69 6e 65 20 73 71 6c 69 74 65 33 5f 63 6f  efine sqlite3_co
1e10: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1e20: 28 58 29 20 30 0a 23 20 64 65 66 69 6e 65 20 73  (X) 0.# define s
1e30: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1e40: 74 69 6f 6e 5f 67 65 74 28 58 29 20 20 28 28 76  tion_get(X)  ((v
1e50: 6f 69 64 2a 29 30 29 0a 23 65 6e 64 69 66 0a 0a  oid*)0).#endif..
1e60: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e70: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1e80: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1e90: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1ea0: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1eb0: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ec0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1ed0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1ee0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1ef0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1f00: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1f10: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1f20: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1f30: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1f40: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1f50: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1f60: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1f70: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1f80: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1f90: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1fa0: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1fb0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1fc0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1fd0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1fe0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1ff0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
2000: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
2010: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2020: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
2030: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
2040: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
2050: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
2060: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
2070: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
2080: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
2090: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
20a0: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
20b0: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
20c0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
20d0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
20e0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
20f0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
2100: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
2110: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
2120: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
2130: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
2140: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
2150: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
2160: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
2170: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
2180: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
2190: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
21a0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
21b0: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
21c0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
21d0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
21e0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
21f0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
2200: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
2210: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
2220: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
2230: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
2240: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
2250: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
2260: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
2270: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
2280: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
2290: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
22a0: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
22b0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
22c0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
22d0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
22e0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
22f0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
2300: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
2310: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2320: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2330: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2340: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2350: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2360: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2370: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2380: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2390: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
23a0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
23b0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
23c0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
23d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
23e0: 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72  LIZED].  ^(The r
23f0: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
2400: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68  he.** sqlite3_th
2410: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
2420: 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74  ion shows only t
2430: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
2440: 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68  setting of.** th
2450: 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74  read safety, not
2460: 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68   any run-time ch
2470: 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65  anges to that se
2480: 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a  tting made by.**
2490: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
24a0: 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ). In other word
24b0: 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  s, the return va
24c0: 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
24d0: 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a  _threadsafe().**
24e0: 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79   is unchanged by
24f0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2500: 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a  3_config().)^.**
2510: 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72  .** See the [thr
2520: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63  eading mode] doc
2530: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
2540: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
2550: 61 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ation..*/.int sq
2560: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
2570: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
2580: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
2590: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e  e Connection Han
25a0: 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  dle.** KEYWORDS:
25b0: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
25c0: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65  ction} {database
25d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a   connections}.**
25e0: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51  .** Each open SQ
25f0: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73  Lite database is
2600: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
2610: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
2620: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74  instance of.** t
2630: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  he opaque struct
2640: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
2650: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
2660: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
2670: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
2680: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
2690: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
26a0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
26b0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
26c0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
26d0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
26e0: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
26f0: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73  tructors, and [s
2700: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a  qlite3_close()].
2710: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2720: 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20  close_v2()] are 
2730: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e  its destructors.
2740: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
2750: 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66   other.** interf
2760: 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a  aces (such as.**
2770: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2780: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
2790: 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
27a0: 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  n()], and.** [sq
27b0: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
27c0: 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75  ut()] to name bu
27d0: 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72  t three) that ar
27e0: 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a  e methods on an.
27f0: 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63  ** sqlite3 objec
2800: 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  t..*/.typedef st
2810: 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c  ruct sqlite3 sql
2820: 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ite3;../*.** CAP
2830: 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e  I3REF: 64-Bit In
2840: 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b  teger Types.** K
2850: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f  EYWORDS: sqlite_
2860: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e  int64 sqlite_uin
2870: 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  t64.**.** Becaus
2880: 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72  e there is no cr
2890: 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79  oss-platform way
28a0: 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62   to specify 64-b
28b0: 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73  it integer types
28c0: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75  .** SQLite inclu
28d0: 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72  des typedefs for
28e0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61   64-bit signed a
28f0: 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  nd unsigned inte
2900: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gers..**.** The 
2910: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e  sqlite3_int64 an
2920: 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  d sqlite3_uint64
2930: 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72   are the preferr
2940: 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69  ed type definiti
2950: 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ons..** The sqli
2960: 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  te_int64 and sql
2970: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
2980: 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66   are supported f
2990: 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20  or backwards.** 
29a0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e  compatibility on
29b0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
29c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
29d0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79   sqlite_int64 ty
29e0: 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e  pes can store in
29f0: 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20  teger values.** 
2a00: 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32  between -9223372
2a10: 30 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64  036854775808 and
2a20: 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37   +92233720368547
2a30: 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e  75807 inclusive.
2a40: 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
2a50: 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  3_uint64 and sql
2a60: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
2a70: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
2a80: 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65  er values .** be
2a90: 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34  tween 0 and +184
2aa0: 34 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31  4674407370955161
2ab0: 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a  5 inclusive..*/.
2ac0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  #ifdef SQLITE_IN
2ad0: 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64  T64_TYPE.  typed
2ae0: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
2af0: 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36  TYPE sqlite_int6
2b00: 34 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54  4;.# ifdef SQLIT
2b10: 45 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20  E_UINT64_TYPE.  
2b20: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
2b30: 5f 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  _UINT64_TYPE sql
2b40: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c  ite_uint64;.# el
2b50: 73 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66  se  .    typedef
2b60: 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45   unsigned SQLITE
2b70: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
2b80: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64  te_uint64;.# end
2b90: 69 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  if.#elif defined
2ba0: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
2bb0: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
2bc0: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
2bd0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
2be0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
2bf0: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
2c00: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2c10: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
2c20: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2c30: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2c40: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
2c50: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2c60: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
2c70: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2c80: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
2c90: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
2ca0: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
2cb0: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
2cc0: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
2cd0: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
2ce0: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
2cf0: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
2d00: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
2d10: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
2d20: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23  ting-point..*/.#
2d30: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
2d40: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
2d50: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
2d60: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
2d70: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2d80: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
2d90: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
2da0: 74 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54  tion.** DESTRUCT
2db0: 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OR: sqlite3.**.*
2dc0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2dd0: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2de0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f  e3_close_v2() ro
2df0: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72  utines are destr
2e00: 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68  uctors.** for th
2e10: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2e20: 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  ct..** ^Calls to
2e30: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2e40: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f   and sqlite3_clo
2e50: 73 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b  se_v2() return [
2e60: 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a  SQLITE_OK] if.**
2e70: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2e80: 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73  bject is success
2e90: 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20  fully destroyed 
2ea0: 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74  and all associat
2eb0: 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20  ed.** resources 
2ec0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ed0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  .**.** ^If the d
2ee0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ef0: 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  on is associated
2f00: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65   with unfinalize
2f10: 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  d prepared.** st
2f20: 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69  atements or unfi
2f30: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62  nished sqlite3_b
2f40: 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68  ackup objects th
2f50: 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  en sqlite3_close
2f60: 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65  ().** will leave
2f70: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2f80: 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e  nnection open an
2f90: 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
2fa0: 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73  _BUSY]..** ^If s
2fb0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2fc0: 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
2fd0: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2fe0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2ff0: 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e  .** and/or unfin
3000: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
3010: 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20  ckups, then the 
3020: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3030: 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61  ion becomes.** a
3040: 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62  n unusable "zomb
3050: 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61  ie" which will a
3060: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20  utomatically be 
3070: 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e  deallocated when
3080: 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65   the.** last pre
3090: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
30a0: 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20  is finalized or 
30b0: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
30c0: 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69  _backup is.** fi
30d0: 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c  nished.  The sql
30e0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
30f0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74  interface is int
3100: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69  ended for use wi
3110: 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75  th.** host langu
3120: 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61  ages that are ga
3130: 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c  rbage collected,
3140: 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f   and where the o
3150: 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a  rder in which.**
3160: 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65   destructors are
3170: 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74   called is arbit
3180: 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  rary..**.** Appl
3190: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
31a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31b0: 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c  e | finalize] al
31c0: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
31d0: 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c  ements],.** [sql
31e0: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20  ite3_blob_close 
31f0: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c  | close] all [BL
3200: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
3210: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61   .** [sqlite3_ba
3220: 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69  ckup_finish | fi
3230: 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74  nish] all [sqlit
3240: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
3250: 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ts associated.**
3260: 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74   with the [sqlit
3270: 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72  e3] object prior
3280: 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74   to attempting t
3290: 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65  o close the obje
32a0: 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69  ct.  ^If.** sqli
32b0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
32c0: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
32d0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32e0: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
32f0: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
3300: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
3310: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3320: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a  andles], and/or.
3330: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
3340: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e  up] objects then
3350: 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c   it returns [SQL
3360: 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20  ITE_OK] and the 
3370: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
3380: 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20  of resources is 
3390: 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
33a0: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
33b0: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20  tements], [BLOB 
33c0: 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64  handles],.** and
33d0: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70   [sqlite3_backup
33e0: 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c  ] objects are al
33f0: 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  so destroyed..**
3400: 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69  .** ^If an [sqli
3410: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64  te3] object is d
3420: 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61  estroyed while a
3430: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
3440: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61  open,.** the tra
3450: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
3460: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
3470: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   back..**.** The
3480: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   C parameter to 
3490: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
34a0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
34b0: 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20  close_v2(C)].** 
34c0: 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
34d0: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
34e0: 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d   or an [sqlite3]
34f0: 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20   object pointer 
3500: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
3510: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
3520: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
3530: 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
3540: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
3550: 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f  , and not previo
3560: 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20  usly closed..** 
3570: 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
3580: 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69  _close() or sqli
3590: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77  te3_close_v2() w
35a0: 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
35b0: 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  er.** argument i
35c0: 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
35d0: 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  op..*/.int sqlit
35e0: 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33  e3_close(sqlite3
35f0: 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
3600: 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33  close_v2(sqlite3
3610: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  *);../*.** The t
3620: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61  ype for a callba
3630: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ck function..** 
3640: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61  This is legacy a
3650: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20  nd deprecated.  
3660: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66  It is included f
3670: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
3680: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61   compatibility a
3690: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65  nd is not docume
36a0: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  nted..*/.typedef
36b0: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63   int (*sqlite3_c
36c0: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
36d0: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a  nt,char**, char*
36e0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
36f0: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75  REF: One-Step Qu
3700: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e  ery Execution In
3710: 74 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f  terface.** METHO
3720: 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
3730: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
3740: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
3750: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
3760: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
3770: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
3780: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3790: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
37a0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
37b0: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c  ()],.** that all
37c0: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
37d0: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70  on to run multip
37e0: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  le statements of
37f0: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20   SQL.** without 
3800: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20  having to use a 
3810: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a  lot of C code. .
3820: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
3830: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
3840: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72  ace runs zero or
3850: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f   more UTF-8 enco
3860: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  ded,.** semicolo
3870: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73  n-separate SQL s
3880: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
3890: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72   into its 2nd ar
38a0: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68  gument,.** in th
38b0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
38c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
38d0: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e  ction] passed in
38e0: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61   as its 1st.** a
38f0: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  rgument.  ^If th
3900: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
3910: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61  ion of the 3rd a
3920: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3930: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3940: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69  not NULL, then i
3950: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72  t is invoked for
3960: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77   each result row
3970: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f  .** coming out o
3980: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20  f the evaluated 
3990: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
39a0: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
39b0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
39c0: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
39d0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
39e0: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
39f0: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
3a00: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
3a10: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3a20: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
3a30: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3a40: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
3a50: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
3a60: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
3a70: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
3a80: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
3a90: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
3aa0: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
3ab0: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
3ac0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
3ad0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3ae0: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
3af0: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
3b00: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
3b10: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
3b20: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
3b30: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
3b40: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3b50: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3b60: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
3b70: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
3b80: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
3b90: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
3ba0: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
3bb0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
3bc0: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
3bd0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
3be0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3bf0: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
3c00: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
3c10: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
3c20: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
3c30: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
3c40: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3c50: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
3c60: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
3c70: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
3c80: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61  sqlite3_exec() a
3c90: 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d  fter the error m
3ca0: 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
3cb0: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
3cc0: 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74  d..** ^If the 5t
3cd0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
3ce0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3cf0: 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f   not NULL and no
3d00: 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72   errors.** occur
3d10: 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65  , then sqlite3_e
3d20: 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70  xec() sets the p
3d30: 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74  ointer in its 5t
3d40: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
3d50: 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65  * NULL before re
3d60: 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  turning..**.** ^
3d70: 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78  If an sqlite3_ex
3d80: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65  ec() callback re
3d90: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
3da0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3db0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
3dc0: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f  turns SQLITE_ABO
3dd0: 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b  RT without invok
3de0: 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ing the callback
3df0: 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69   again and.** wi
3e00: 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e  thout running an
3e10: 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c  y subsequent SQL
3e20: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
3e30: 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75  ** ^The 2nd argu
3e40: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
3e50: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3e60: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ack function is 
3e70: 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
3e80: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
3e90: 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72  result.  ^The 3r
3ea0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
3eb0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3ec0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  .** callback is 
3ed0: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
3ee0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
3ef0: 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66  obtained as if f
3f00: 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
3f10: 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
3f20: 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c  one for each col
3f30: 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65  umn.  ^If an ele
3f40: 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73  ment of a.** res
3f50: 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20  ult row is NULL 
3f60: 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  then the corresp
3f70: 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f  onding string po
3f80: 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a  inter for the.**
3f90: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3fa0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55  callback is a NU
3fb0: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
3fc0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
3fd0: 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  o the.** sqlite3
3fe0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3ff0: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
4000: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
4010: 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a  ngs where each.*
4020: 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e  * entry represen
4030: 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63  ts the name of c
4040: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73  orresponding res
4050: 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62  ult column as ob
4060: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
4070: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
4080: 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ame()]..**.** ^I
4090: 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
40a0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
40b0: 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  xec() is a NULL 
40c0: 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74  pointer, a point
40d0: 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74  er.** to an empt
40e0: 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70  y string, or a p
40f0: 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74  ointer that cont
4100: 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73  ains only whites
4110: 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20  pace and/or .** 
4120: 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68  SQL comments, th
4130: 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d  en no SQL statem
4140: 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74  ents are evaluat
4150: 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  ed and the datab
4160: 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ase.** is not ch
4170: 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73  anged..**.** Res
4180: 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a  trictions:.**.**
4190: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
41a0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
41b0: 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  st ensure that t
41c0: 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
41d0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
41e0: 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20  ().**      is a 
41f0: 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b  valid and open [
4200: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4210: 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ion]..** <li> Th
4220: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
4230: 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
4240: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
4250: 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
4260: 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20   by.**      the 
4270: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
4280: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4290: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
42a0: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
42b0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
42c0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
42d0: 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c  t modify the SQL
42e0: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
42f0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20  passed into.**  
4300: 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61      the 2nd para
4310: 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
4320: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
4330: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
4340: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c  running..** </ul
4350: 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
4360: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
4370: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
4380: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4390: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
43a0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
43b0: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
43c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43d0: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
43e0: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
43f0: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
4400: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
4410: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
4420: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
4430: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  void *,
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4450: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4460: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
4470: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
4480: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
4490: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
44a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
44b0: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
44c0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
44d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
44e0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
44f0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75   KEYWORDS: {resu
4500: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4510: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  ons}.**.** Many 
4520: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
4530: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
4540: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
4550: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
4560: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
4570: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73  er to indicate s
4580: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
4590: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
45a0: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
45b0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
45c0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
45d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
45e0: 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  so: [extended re
45f0: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4600: 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e  tions].*/.#defin
4610: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
4620: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
4630: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
4640: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f  /./* beginning-o
4650: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4670: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20  ERROR        1  
4680: 20 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f   /* Generic erro
4690: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
46a0: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20  ITE_INTERNAL    
46b0: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c   2   /* Internal
46c0: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
46d0: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e  SQLite */.#defin
46e0: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20  e SQLITE_PERM   
46f0: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63        3   /* Acc
4700: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64  ess permission d
4710: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4720: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20   SQLITE_ABORT   
4730: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c       4   /* Call
4740: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
4750: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
4760: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4770: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35  E_BUSY         5
4780: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4790: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65  se file is locke
47a0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
47b0: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20  ITE_LOCKED      
47c0: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20   6   /* A table 
47d0: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
47e0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
47f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
4800: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  M        7   /* 
4810: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65  A malloc() faile
4820: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4830: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  ITE_READONLY    
4840: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20   8   /* Attempt 
4850: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f  to write a reado
4860: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  nly database */.
4870: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4880: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20  NTERRUPT    9   
4890: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72  /* Operation ter
48a0: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74  minated by sqlit
48b0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f  e3_interrupt()*/
48c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48d0: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20  IOERR       10  
48e0: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66   /* Some kind of
48f0: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20   disk I/O error 
4900: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66  occurred */.#def
4910: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
4920: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54  PT     11   /* T
4930: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  he database disk
4940: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72   image is malfor
4950: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  med */.#define S
4960: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20  QLITE_NOTFOUND  
4970: 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77    12   /* Unknow
4980: 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69  n opcode in sqli
4990: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
49a0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
49b0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
49c0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
49d0: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
49e0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
49f0: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
4a00: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
4a10: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
4a20: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
4a30: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4a40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
4a50: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
4a60: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72  Database lock pr
4a70: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a  otocol error */.
4a80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4a90: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20  MPTY       16   
4aa0: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20  /* Internal use 
4ab0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
4ac0: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20  SQLITE_SCHEMA   
4ad0: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64     17   /* The d
4ae0: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
4af0: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e  hanged */.#defin
4b00: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20  e SQLITE_TOOBIG 
4b10: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72       18   /* Str
4b20: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65  ing or BLOB exce
4b30: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a  eds size limit *
4b40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b50: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20  _CONSTRAINT  19 
4b60: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74    /* Abort due t
4b70: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  o constraint vio
4b80: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e  lation */.#defin
4b90: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  e SQLITE_MISMATC
4ba0: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74  H    20   /* Dat
4bb0: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20  a type mismatch 
4bc0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4bd0: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31  E_MISUSE      21
4be0: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73     /* Library us
4bf0: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a  ed incorrectly *
4c00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4c10: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20  _NOLFS       22 
4c20: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61    /* Uses OS fea
4c30: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72  tures not suppor
4c40: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23  ted on host */.#
4c50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
4c60: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f  TH        23   /
4c70: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  * Authorization 
4c80: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
4c90: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20  e SQLITE_FORMAT 
4ca0: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74       24   /* Not
4cb0: 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
4cc0: 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20   SQLITE_RANGE   
4cd0: 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20      25   /* 2nd 
4ce0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
4cf0: 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66  ite3_bind out of
4d00: 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e   range */.#defin
4d10: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20  e SQLITE_NOTADB 
4d20: 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c       26   /* Fil
4d30: 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73  e opened that is
4d40: 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
4d50: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4d60: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20  SQLITE_NOTICE   
4d70: 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66     27   /* Notif
4d80: 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71  ications from sq
4d90: 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23  lite3_log() */.#
4da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41  define SQLITE_WA
4db0: 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f  RNING     28   /
4dc0: 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20  * Warnings from 
4dd0: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f  sqlite3_log() */
4de0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4df0: 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20  ROW         100 
4e00: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4e10: 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72  () has another r
4e20: 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66  ow ready */.#def
4e30: 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20  ine SQLITE_DONE 
4e40: 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73         101  /* s
4e50: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
4e60: 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
4e70: 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f  ting */./* end-o
4e80: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4e90: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4ea0: 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  : Extended Resul
4eb0: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4ec0: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
4ed0: 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e  esult code defin
4ee0: 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e  itions}.**.** In
4ef0: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
4f00: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
4f10: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
4f20: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30  return one of 30
4f30: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73   integer.** [res
4f40: 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77  ult codes].  How
4f50: 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65  ever, experience
4f60: 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20   has shown that 
4f70: 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65  many of.** these
4f80: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4f90: 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61  e too coarse-gra
4fa0: 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e  ined.  They do n
4fb0: 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a  ot provide as.**
4fc0: 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f   much informatio
4fd0: 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73  n about problems
4fe0: 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20   as programmers 
4ff0: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20  might like.  In 
5000: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20  an effort to.** 
5010: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65  address this, ne
5020: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
5030: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20  SQLite (version 
5040: 33 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e  3.3.8 [dateof:3.
5050: 33 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65  3.8].** and late
5060: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75  r) include.** su
5070: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69  pport for additi
5080: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65  onal result code
5090: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d  s that provide m
50a0: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66  ore detailed inf
50b0: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
50c0: 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20  t errors. These 
50d0: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
50e0: 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62   codes] are enab
50f0: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
5100: 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61  ** on a per data
5110: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
5120: 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a  basis using the.
5130: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  ** [sqlite3_exte
5140: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
5150: 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74  s()] API.  Or, t
5160: 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65  he extended code
5170: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74   for.** the most
5180: 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61   recent error ca
5190: 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73  n be obtained us
51a0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
51b0: 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
51c0: 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
51d0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53  SQLITE_ERROR_MIS
51e0: 53 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28  SING_COLLSEQ   (
51f0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28  SQLITE_ERROR | (
5200: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5210: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52  QLITE_ERROR_RETR
5220: 59 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  Y             (S
5230: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32  QLITE_ERROR | (2
5240: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5250: 4c 49 54 45 5f 45 52 52 4f 52 5f 53 4e 41 50 53  LITE_ERROR_SNAPS
5260: 48 4f 54 20 20 20 20 20 20 20 20 20 20 28 53 51  HOT          (SQ
5270: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 33 3c  LITE_ERROR | (3<
5280: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5290: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
52a0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
52b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
52c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
52d0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
52e0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
52f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
5300: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5310: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5320: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5330: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5340: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5350: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5360: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5370: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5390: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
53a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
53b0: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
53c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
53d0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
53e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
53f0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
5400: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5410: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5420: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5430: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5450: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5460: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5470: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5490: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
54a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
54b0: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
54c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54d0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
54e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54f0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
5500: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5510: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5520: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5530: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5540: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5550: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5560: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5570: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5580: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5590: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
55a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55b0: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
55c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55d0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
55e0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
55f0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
5600: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5610: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5620: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5630: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5640: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5650: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5660: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5670: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5680: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5690: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
56a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56b0: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
56c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56d0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
56e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56f0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
5700: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5710: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5720: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5730: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5740: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5750: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5760: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5770: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5780: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5790: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
57a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57b0: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
57c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57d0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
57e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57f0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5800: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5810: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5820: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5830: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5840: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5850: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
5860: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5870: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
5880: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5890: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
58a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58b0: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
58c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58d0: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
58e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58f0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
5900: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5910: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
5920: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5930: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
5940: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5950: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
5960: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5970: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
5980: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5990: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20  _BEGIN_ATOMIC   
59a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
59b0: 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66   | (29<<8)).#def
59c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
59d0: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20  _COMMIT_ATOMIC  
59e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
59f0: 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66   | (30<<8)).#def
5a00: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5a10: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
5a20: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5a30: 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66   | (31<<8)).#def
5a40: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5a50: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5a60: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5a70: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5a80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5a90: 45 44 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  ED_VTAB         
5aa0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
5ab0: 45 44 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64  ED |  (2<<8)).#d
5ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5ad0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5ae0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5af0: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
5b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5b10: 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20  SY_SNAPSHOT     
5b20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5b30: 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a  SY   |  (2<<8)).
5b40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5b50: 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49  ANTOPEN_NOTEMPDI
5b60: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5b70: 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29  ANTOPEN | (1<<8)
5b80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5b90: 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20  _CANTOPEN_ISDIR 
5ba0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5bb0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c  _CANTOPEN | (2<<
5bc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5bd0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c  TE_CANTOPEN_FULL
5be0: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5bf0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33  TE_CANTOPEN | (3
5c00: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5c10: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f  LITE_CANTOPEN_CO
5c20: 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51  NVPATH       (SQ
5c30: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5c40: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5c50: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
5c60: 44 49 52 54 59 57 41 4c 20 20 20 20 20 20 20 28  DIRTYWAL       (
5c70: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5c80: 7c 20 28 35 3c 3c 38 29 29 20 2f 2a 20 4e 6f 74  | (5<<8)) /* Not
5c90: 20 55 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   Used */.#define
5ca0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5cb0: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
5cc0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5cd0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5ce0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
5cf0: 5f 53 45 51 55 45 4e 43 45 20 20 20 20 20 20 20  _SEQUENCE       
5d00: 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   (SQLITE_CORRUPT
5d10: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5d20: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5d30: 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  LY_RECOVERY     
5d40: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5d50: 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  LY | (1<<8)).#de
5d60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5d70: 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20  ONLY_CANTLOCK   
5d80: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5d90: 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23  ONLY | (2<<8)).#
5da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
5db0: 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20  ADONLY_ROLLBACK 
5dc0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
5dd0: 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29  ADONLY | (3<<8))
5de0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5df0: 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44  READONLY_DBMOVED
5e00: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5e10: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38  READONLY | (4<<8
5e20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5e30: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49  E_READONLY_CANTI
5e40: 4e 49 54 20 20 20 20 20 20 20 28 53 51 4c 49 54  NIT       (SQLIT
5e50: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c  E_READONLY | (5<
5e60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5e70: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52  ITE_READONLY_DIR
5e80: 45 43 54 4f 52 59 20 20 20 20 20 20 28 53 51 4c  ECTORY      (SQL
5e90: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5ea0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5eb0: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
5ec0: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
5ed0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
5ee0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5ef0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5f00: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
5f10: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5f20: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5f30: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5f40: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
5f50: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5f60: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
5f70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5f80: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
5f90: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
5fa0: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
5fb0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5fc0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
5fd0: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5fe0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5ff0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6000: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
6010: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
6020: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
6030: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
6040: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
6050: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
6060: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
6070: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
6080: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
6090: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
60a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
60b0: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
60c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
60d0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
60e0: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
60f0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
6100: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6110: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
6120: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
6130: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
6140: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
6150: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
6160: 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20  INT_ROWID       
6170: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
6180: 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64  INT |(10<<8)).#d
6190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
61a0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20  ICE_RECOVER_WAL 
61b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54       (SQLITE_NOT
61c0: 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ICE | (1<<8)).#d
61d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
61e0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c  ICE_RECOVER_ROLL
61f0: 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54  BACK (SQLITE_NOT
6200: 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ICE | (2<<8)).#d
6210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
6220: 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20  NING_AUTOINDEX  
6230: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52       (SQLITE_WAR
6240: 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23  NING | (1<<8)).#
6250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
6260: 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20  TH_USER         
6270: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55        (SQLITE_AU
6280: 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  TH | (1<<8)).#de
6290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c  fine SQLITE_OK_L
62a0: 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20  OAD_PERMANENTLY 
62b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c      (SQLITE_OK |
62c0: 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20   (1<<8))../*.** 
62d0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
62e0: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70  For File Open Op
62f0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  erations.**.** T
6300: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
6310: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
6320: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
6330: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
6340: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
6350: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
6360: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
6370: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
6380: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
6390: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e  s.xOpen] method.
63a0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
63b0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
63c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
63d0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
63e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
63f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6400: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
6410: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6420: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
6430: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6440: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6450: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
6460: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6470: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
6480: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6490: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
64a0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
64b0: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
64c0: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
64d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
64e0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
64f0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6500: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
6510: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6520: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
6530: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
6540: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
6550: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6560: 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20  TE_OPEN_URI     
6570: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6580: 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  040  /* Ok for s
6590: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
65a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
65b0: 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20  TE_OPEN_MEMORY  
65c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
65d0: 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  080  /* Ok for s
65e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
65f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6600: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
6610: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6620: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
6630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6640: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
6650: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6660: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
6670: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6680: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
6690: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
66a0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
66b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
66c0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
66d0: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
66e0: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
66f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6700: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
6710: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
6720: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6730: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6740: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
6750: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
6760: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6770: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6780: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
6790: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
67a0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
67b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
67c0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
67d0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
67e0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
67f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6800: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6810: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
6820: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
6830: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6840: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6850: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6860: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
6870: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
6880: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6890: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
68a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
68b0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
68c0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
68d0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
68e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
68f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6900: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
6910: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
6920: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6930: 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64   */../* Reserved
6940: 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  :               
6950: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30            0x00F0
6960: 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  0000 */../*.** C
6970: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20  API3REF: Device 
6980: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a  Characteristics.
6990: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
69a0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
69b0: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
69c0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
69d0: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
69e0: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
69f0: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
6a00: 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62  or of these.** b
6a10: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
6a20: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
6a30: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
6a40: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
6a50: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
6a60: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
6a70: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
6a80: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
6a90: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
6aa0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6ab0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
6ac0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
6ad0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
6ae0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
6af0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6b00: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
6b10: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
6b20: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
6b30: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
6b40: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
6b50: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
6b60: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
6b70: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
6b80: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
6b90: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
6ba0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6bb0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
6bc0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
6bd0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
6be0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
6bf0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
6c00: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
6c10: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
6c20: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
6c30: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
6c40: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
6c50: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
6c60: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6c70: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
6c80: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
6c90: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
6ca0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
6cb0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
6cc0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
6cd0: 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ().  The SQLITE_
6ce0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6cf0: 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72  OVERWRITE proper
6d00: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
6d10: 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f   after reboot fo
6d20: 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20  llowing a crash 
6d30: 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74  or power loss, t
6d40: 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e  he only bytes in
6d50: 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20   a.** file that 
6d60: 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20  were written at 
6d70: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
6d80: 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65  level might have
6d90: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20   changed.** and 
6da0: 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79  that adjacent by
6db0: 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20  tes, even bytes 
6dc0: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
6dd0: 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75  sector are.** gu
6de0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75  aranteed to be u
6df0: 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53  nchanged.  The S
6e00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
6e10: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
6e20: 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61  N.** flag indica
6e30: 74 65 73 20 74 68 61 74 20 61 20 66 69 6c 65 20  tes that a file 
6e40: 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65  cannot be delete
6e50: 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68  d when open.  Th
6e60: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41  e.** SQLITE_IOCA
6e70: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67  P_IMMUTABLE flag
6e80: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
6e90: 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a  the file is on.*
6ea0: 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69  * read-only medi
6eb0: 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20  a and cannot be 
6ec0: 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20  changed even by 
6ed0: 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a  processes with.*
6ee0: 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69  * elevated privi
6ef0: 6c 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  leges..**.** The
6f00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41   SQLITE_IOCAP_BA
6f10: 54 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  TCH_ATOMIC prope
6f20: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 74  rty means that t
6f30: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a  he underlying.**
6f40: 20 66 69 6c 65 73 79 73 74 65 6d 20 73 75 70 70   filesystem supp
6f50: 6f 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69  orts doing multi
6f60: 70 6c 65 20 77 72 69 74 65 20 6f 70 65 72 61 74  ple write operat
6f70: 69 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20  ions atomically 
6f80: 77 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72  when those.** wr
6f90: 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ite operations a
6fa0: 72 65 20 62 72 61 63 6b 65 74 65 64 20 62 79 20  re bracketed by 
6fb0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
6fc0: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
6fd0: 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  ] and.** [SQLITE
6fe0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54  _FCNTL_COMMIT_AT
6ff0: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a  OMIC_WRITE]..*/.
7000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7010: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
7020: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
7030: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
7040: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7050: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
7060: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
7070: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
7080: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
7090: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
70a0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
70b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
70c0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
70d0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
70e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
70f0: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
7100: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
7110: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
7120: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
7130: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
7140: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
7150: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
7160: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
7170: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
7180: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7190: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
71a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
71b0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
71c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
71d0: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
71e0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
71f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7200: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
7210: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
7220: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
7230: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
7240: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
7250: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
7260: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
7270: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
7280: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
7290: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  800.#define SQLI
72a0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
72b0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
72c0: 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69  0x00001000.#defi
72d0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
72e0: 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20  IMMUTABLE       
72f0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
7300: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
7310: 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f  _IOCAP_BATCH_ATO
7320: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 30 78  MIC           0x
7330: 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00004000../*.** 
7340: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
7350: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a  ocking Levels.**
7360: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
7370: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
7380: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
7390: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
73a0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
73b0: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
73c0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
73d0: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
73e0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
73f0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
7400: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
7410: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
7420: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
7430: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
7440: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
7450: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
7460: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
7470: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
7480: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
7490: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
74a0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
74b0: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
74c0: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
74d0: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
74e0: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  Flags.**.** When
74f0: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
7500: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
7510: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
7520: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
7530: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
7540: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
7550: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
7560: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
7570: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
7580: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
7590: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
75a0: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
75b0: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
75c0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
75d0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
75e0: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
75f0: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
7600: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
7610: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
7620: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74  be flushed. If t
7630: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
7640: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a  ts of the flag.*
7650: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  * equal SQLITE_S
7660: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74  YNC_NORMAL, that
7670: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
7680: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
7690: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68  antics..** If th
76a0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
76b0: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  s equal SQLITE_S
76c0: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d  YNC_FULL, that m
76d0: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
76e0: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
76f0: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
7700: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a  f fsync()..**.**
7710: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20   Do not confuse 
7720: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
7730: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
7740: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
7750: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50  s.** with the [P
7760: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
7770: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50  s]=NORMAL and [P
7780: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
7790: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69  s]=FULL.** setti
77a0: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68  ngs.  The [synch
77b0: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64  ronous pragma] d
77c0: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63  etermines when c
77d0: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  alls to the.** x
77e0: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20  Sync VFS method 
77f0: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65  occur and applie
7800: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f  s uniformly acro
7810: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73  ss all platforms
7820: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
7830: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7840: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7850: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65   flags determine
7860: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69   how.** energeti
7870: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72  c or rigorous or
7880: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79   forceful the sy
7890: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  nc operations ar
78a0: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61  e and.** only ma
78b0: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20  ke a difference 
78c0: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74  on Mac OSX for t
78d0: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74  he default SQLit
78e0: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72  e code..** (Thir
78f0: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c  d-party VFS impl
7900: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68  ementations migh
7910: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20  t also make the 
7920: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
7930: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59  etween SQLITE_SY
7940: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
7950: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
7960: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a  but among the.**
7970: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
7980: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70  ms natively supp
7990: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c  orted by SQLite,
79a0: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a   only Mac OSX.**
79b0: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65   cares about the
79c0: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f   difference.).*/
79d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
79e0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
79f0: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
7a00: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
7a10: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
7a20: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
7a30: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7a40: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
7a50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7a60: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
7a70: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
7a80: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
7a90: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
7aa0: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
7ab0: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20  file in the .** 
7ac0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f  [sqlite3_vfs | O
7ad0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
7ae0: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  r].  Individual 
7af0: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  OS interface.** 
7b00: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7b10: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
7b20: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
7b30: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
7b40: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
7b50: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
7b60: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
7b70: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
7b80: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
7b90: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
7ba0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
7bb0: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
7bc0: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
7bd0: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
7be0: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
7bf0: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
7c00: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
7c10: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
7c20: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
7c30: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
7c40: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
7c50: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
7c60: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
7c70: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
7c80: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
7c90: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
7ca0: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
7cb0: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
7cc0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
7cd0: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
7ce0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7cf0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70  .xOpen] method p
7d00: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
7d10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7d20: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
7d30: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
7d40: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
7d50: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7d60: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
7d70: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
7d80: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
7d90: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
7da0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
7db0: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
7dc0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
7dd0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
7de0: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
7df0: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
7e00: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7e10: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
7e20: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
7e30: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7e40: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c  hod sets the sql
7e50: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7e60: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74  ds element .** t
7e70: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  o a non-NULL poi
7e80: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73  nter, then the s
7e90: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7ea0: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a  s.xClose method.
7eb0: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ** may be invoke
7ec0: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73  d even if the [s
7ed0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7ee0: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  ] reported that 
7ef0: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
7f00: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
7f10: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
7f20: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
7f30: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69  g a failed [sqli
7f40: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a  te3_vfs.xOpen].*
7f50: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71  * is for the [sq
7f60: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7f70: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
7f80: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7f90: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20  s element.** to 
7fa0: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
7fb0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
7fc0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
7fd0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
7fe0: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
7ff0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
8000: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
8010: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
8020: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
8030: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
8040: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
8050: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
8060: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
8070: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
8080: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
8090: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
80a0: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
80b0: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
80c0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
80d0: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
80e0: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
80f0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
8100: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
8110: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
8120: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
8130: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
8140: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
8150: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
8160: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
8170: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
8180: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
8190: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
81a0: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
81b0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
81c0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
81d0: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
81e0: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
81f0: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
8200: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
8210: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
8220: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
8230: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
8240: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
8250: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
8260: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
8270: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
8280: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
8290: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
82a0: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
82b0: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
82c0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
82d0: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
82e0: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
82f0: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
8300: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
8310: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
8320: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
8330: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
8340: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
8350: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
8360: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
8370: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
8380: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
8390: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
83a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
83b0: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
83c0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
83d0: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
83e0: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
83f0: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
8400: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
8410: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
8420: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
8430: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
8440: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
8450: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
8460: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
8470: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
8480: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
8490: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
84a0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
84b0: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
84c0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
84d0: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
84e0: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
84f0: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
8500: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
8510: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
8520: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
8530: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
8540: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
8550: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
8560: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
8570: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
8580: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
8590: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
85a0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
85b0: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
85c0: 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c   A [file control
85d0: 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20   opcodes | list 
85e0: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
85f0: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
8600: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
8610: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
8620: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
8630: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8640: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
8650: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
8660: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
8670: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
8680: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
8690: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
86a0: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
86b0: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
86c0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
86d0: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
86e0: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
86f0: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
8700: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
8710: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
8720: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
8730: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
8740: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
8750: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
8760: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
8770: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
8780: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
8790: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
87a0: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
87b0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
87c0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
87d0: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
87e0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
87f0: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
8800: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
8810: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
8820: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
8830: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
8840: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8850: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
8860: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
8870: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
8880: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8890: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
88a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
88b0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
88c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
88d0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
88e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
88f0: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
8900: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8910: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
8920: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8930: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
8940: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8950: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
8960: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
8970: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
8980: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8990: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
89a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
89b0: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
89c0: 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e  EN_OPEN].** <li>
89d0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
89e0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
89f0: 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  TE].** <li> [SQL
8a00: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
8a10: 42 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  BLE].** <li> [SQ
8a20: 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48  LITE_IOCAP_BATCH
8a30: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c  _ATOMIC].** </ul
8a40: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
8a50: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
8a60: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8a70: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
8a80: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
8a90: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8aa0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8ab0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
8ac0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
8ad0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
8ae0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
8af0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
8b00: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
8b10: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
8b20: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
8b30: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
8b40: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8b50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8b60: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
8b70: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
8b80: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8b90: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
8ba0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8bb0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
8bc0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
8bd0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
8be0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
8bf0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
8c00: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8c10: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
8c20: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
8c30: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
8c40: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
8c50: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
8c60: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
8c70: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
8c80: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
8c90: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
8ca0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
8cb0: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
8cc0: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
8cd0: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
8ce0: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
8cf0: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
8d00: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
8d10: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
8d20: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
8d30: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
8d40: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
8d50: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8d60: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
8d70: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
8d80: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
8d90: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
8da0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
8db0: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
8dc0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
8dd0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
8de0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
8df0: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
8e00: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
8e10: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8e20: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
8e30: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
8e40: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
8e50: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
8e60: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
8e70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
8e80: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
8e90: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
8ea0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
8eb0: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
8ec0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8ed0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
8ee0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
8ef0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8f00: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
8f10: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
8f20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8f30: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
8f40: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
8f50: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8f60: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
8f70: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
8f80: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
8f90: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
8fa0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
8fb0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
8fc0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
8fd0: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
8fe0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8ff0: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
9000: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
9010: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
9020: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
9030: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
9040: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
9050: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65  _file*);.  /* Me
9060: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
9070: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
9080: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 1 */.  int (*x
9090: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f  ShmMap)(sqlite3_
90a0: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20  file*, int iPg, 
90b0: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76  int pgsz, int, v
90c0: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b  oid volatile**);
90d0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
90e0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
90f0: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e  , int offset, in
9100: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  t n, int flags);
9110: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
9120: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
9130: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
9140: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65  ShmUnmap)(sqlite
9150: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
9160: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
9170: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
9180: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
9190: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 2 */.  int (*
91a0: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  xFetch)(sqlite3_
91b0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
91c0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20  nt64 iOfst, int 
91d0: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29  iAmt, void **pp)
91e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74  ;.  int (*xUnfet
91f0: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
9200: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
9210: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29   iOfst, void *p)
9220: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
9230: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
9240: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a  or version 3 */.
9250: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
9260: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
9270: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
9280: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
9290: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
92a0: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
92b0: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20  trol Opcodes.** 
92c0: 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20  KEYWORDS: {file 
92d0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d  control opcodes}
92e0: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
92f0: 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  pcode}.**.** The
9300: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
9310: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73  ants are opcodes
9320: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f   for the xFileCo
9330: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20  ntrol method.** 
9340: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
9350: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
9360: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b  ct and for the [
9370: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9380: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
9390: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  face..**.** <ul>
93a0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
93b0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
93c0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
93d0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
93e0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
93f0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
9400: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
9410: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
9420: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
9430: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
9440: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
9450: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
9460: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
9470: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
9480: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
9490: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
94a0: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
94b0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
94c0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
94d0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
94e0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
94f0: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
9500: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
9510: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
9520: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
9530: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20   testing and is 
9540: 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77  only available w
9550: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hen the SQLITE_T
9560: 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  EST.** compile-t
9570: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  ime option is us
9580: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
9590: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
95a0: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
95b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
95c0: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
95d0: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
95e0: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
95f0: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
9600: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
9610: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9620: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
9630: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
9640: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
9650: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
9660: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
9670: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
9680: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
9690: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
96a0: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
96b0: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
96c0: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
96d0: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
96e0: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
96f0: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
9700: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
9710: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
9720: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
9730: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9740: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 4c 49  TE_FCNTL_SIZE_LI
9750: 4d 49 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  MIT]].** The [SQ
9760: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
9770: 4c 49 4d 49 54 5d 20 6f 70 63 6f 64 65 20 69 73  LIMIT] opcode is
9780: 20 75 73 65 64 20 62 79 20 69 6e 2d 6d 65 6d 6f   used by in-memo
9790: 72 79 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 69  ry VFS that.** i
97a0: 6d 70 6c 65 6d 65 6e 74 73 20 5b 73 71 6c 69 74  mplements [sqlit
97b0: 65 33 5f 64 65 73 65 72 69 61 6c 69 7a 65 28 29  e3_deserialize()
97c0: 5d 20 74 6f 20 73 65 74 20 61 6e 20 75 70 70 65  ] to set an uppe
97d0: 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73  r bound on the s
97e0: 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 65 20 69 6e  ize.** of the in
97f0: 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
9800: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
9810: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
9820: 61 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  a [sqlite3_int64
9830: 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74  ]..** If the int
9840: 65 67 65 72 20 70 6f 69 6e 74 65 64 20 74 6f 20  eger pointed to 
9850: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
9860: 6e 20 69 74 20 69 73 20 66 69 6c 6c 65 64 20 69  n it is filled i
9870: 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 63 75  n with the.** cu
9880: 72 72 65 6e 74 20 6c 69 6d 69 74 2e 20 20 4f 74  rrent limit.  Ot
9890: 68 65 72 77 69 73 65 20 74 68 65 20 6c 69 6d 69  herwise the limi
98a0: 74 20 69 73 20 73 65 74 20 74 6f 20 74 68 65 20  t is set to the 
98b0: 6c 61 72 67 65 72 20 6f 66 20 74 68 65 20 76 61  larger of the va
98c0: 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 69 6e  lue.** of the in
98d0: 74 65 67 65 72 20 70 6f 69 6e 74 65 64 20 74 6f  teger pointed to
98e0: 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74   and the current
98f0: 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 2e 20   database size. 
9900: 20 54 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   The integer.** 
9910: 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 73 65  pointed to is se
9920: 74 20 74 6f 20 74 68 65 20 6e 65 77 20 6c 69 6d  t to the new lim
9930: 69 74 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  it..**.** <li>[[
9940: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
9950: 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65  NK_SIZE]].** The
9960: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
9970: 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64  HUNK_SIZE] opcod
9980: 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71  e is used to req
9990: 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46  uest that the VF
99a0: 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64  S.** extends and
99b0: 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64   truncates the d
99c0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20  atabase file in 
99d0: 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65  chunks of a size
99e0: 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
99f0: 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66   the user. The f
9a00: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
9a10: 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  o [sqlite3_file_
9a20: 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c  control()] shoul
9a30: 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  d .** point to a
9a40: 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20  n integer (type 
9a50: 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  int) containing 
9a60: 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69  the new chunk-si
9a70: 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72  ze to use.** for
9a80: 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64   the nominated d
9a90: 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74  atabase. Allocat
9aa0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c  ing database fil
9ab0: 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65  e space in large
9ac0: 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20  .** chunks (say 
9ad0: 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20  1MB at a time), 
9ae0: 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d  may reduce file-
9af0: 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61  system fragmenta
9b00: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72  tion and.** impr
9b10: 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ove performance 
9b20: 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e  on some systems.
9b30: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9b40: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
9b50: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20  OINTER]].** The 
9b60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
9b70: 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  LE_POINTER] opco
9b80: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62  de is used to ob
9b90: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  tain a pointer.*
9ba0: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
9bb0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61  3_file] object a
9bc0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
9bd0: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
9be0: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
9bf0: 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53  on.  See also [S
9c00: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52  QLITE_FCNTL_JOUR
9c10: 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a  NAL_POINTER]..**
9c20: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9c30: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
9c40: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20  OINTER]].** The 
9c50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f  [SQLITE_FCNTL_JO
9c60: 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f  URNAL_POINTER] o
9c70: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9c80: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65   obtain a pointe
9c90: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  r.** to the [sql
9ca0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
9cb0: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
9cc0: 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69  h the journal fi
9cd0: 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a 20 74 68  le (either.** th
9ce0: 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72  e [rollback jour
9cf0: 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72 69  nal] or the [wri
9d00: 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20 66  te-ahead log]) f
9d10: 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
9d20: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
9d30: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73  ection.  See als
9d40: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  o [SQLITE_FCNTL_
9d50: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a  FILE_POINTER]..*
9d60: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9d70: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
9d80: 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e  TTED]].** No lon
9d90: 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a  ger in use..**.*
9da0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9db0: 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54  CNTL_SYNC]].** T
9dc0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9dd0: 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73  _SYNC] opcode is
9de0: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
9df0: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20  nally by SQLite 
9e00: 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74  and.** sent to t
9e10: 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65  he VFS immediate
9e20: 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53  ly before the xS
9e30: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  ync method is in
9e40: 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61  voked on a.** da
9e50: 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63  tabase file desc
9e60: 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74  riptor. Or, if t
9e70: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20  he xSync method 
9e80: 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a  is not invoked .
9e90: 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75  ** because the u
9ea0: 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72  ser has configur
9eb0: 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a  ed SQLite with .
9ec0: 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  ** [PRAGMA synch
9ed0: 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20  ronous | PRAGMA 
9ee0: 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d  synchronous=OFF]
9ef0: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69   it is invoked i
9f00: 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74  n place .** of t
9f10: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e  he xSync method.
9f20: 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20   In most cases, 
9f30: 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  the pointer argu
9f40: 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68  ment passed with
9f50: 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  .** this file-co
9f60: 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48  ntrol is NULL. H
9f70: 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64  owever, if the d
9f80: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
9f90: 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20  being synced.** 
9fa0: 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c  as part of a mul
9fb0: 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d  ti-database comm
9fc0: 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74  it, the argument
9fd0: 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c   points to a nul
9fe0: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
9ff0: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
a000: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
a010: 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c  s master-journal
a020: 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65   file name. VFSe
a030: 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f  s that .** do no
a040: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
a050: 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  al should silent
a060: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
a070: 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69  pcode. Applicati
a080: 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ons .** should n
a090: 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  ot call [sqlite3
a0a0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
a0b0: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
a0c0: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
a0d0: 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68  y .** disrupt th
a0e0: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  e operation of t
a0f0: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
a100: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
a110: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
a120: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a130: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
a140: 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TWO]].** The [SQ
a150: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
a160: 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f  T_PHASETWO] opco
a170: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
a180: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51  internally by SQ
a190: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74  Lite.** and sent
a1a0: 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65   to the VFS afte
a1b0: 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
a1c0: 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74  has been committ
a1d0: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a  ed immediately.*
a1e0: 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65  * but before the
a1f0: 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c   database is unl
a200: 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61  ocked. VFSes tha
a210: 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  t do not need th
a220: 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f  is signal.** sho
a230: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
a240: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
a250: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
a260: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a  ould not call.**
a270: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
a280: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
a290: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
a2a0: 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75  ing so may disru
a2b0: 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61  pt the .** opera
a2c0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
a2d0: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
a2e0: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
a2f0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
a300: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
a310: 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a  32_AV_RETRY]].**
a320: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a330: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
a340: 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  RY] opcode is us
a350: 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20  ed to configure 
a360: 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74  automatic.** ret
a370: 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e  ry counts and in
a380: 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74  tervals for cert
a390: 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65  ain disk I/O ope
a3a0: 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a  rations for the.
a3b0: 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d  ** windows [VFS]
a3c0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
a3d0: 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20  vide robustness 
a3e0: 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  in the presence 
a3f0: 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73  of.** anti-virus
a400: 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64   programs.  By d
a410: 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64  efault, the wind
a420: 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74  ows VFS will ret
a430: 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a  ry file read,.**
a440: 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64   file write, and
a450: 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65   file delete ope
a460: 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30  rations up to 10
a470: 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64   times, with a d
a480: 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69  elay.** of 25 mi
a490: 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72  lliseconds befor
a4a0: 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72  e the first retr
a4b0: 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64  y and with the d
a4c0: 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a  elay increasing.
a4d0: 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f  ** by an additio
a4e0: 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  nal 25 milliseco
a4f0: 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75  nds with each su
a500: 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20  bsequent retry. 
a510: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
a520: 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f  allows these two
a530: 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72   values (10 retr
a540: 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69  ies and 25 milli
a550: 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79  seconds of delay
a560: 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73  ).** to be adjus
a570: 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73  ted.  The values
a580: 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72   are changed for
a590: 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f   all database co
a5a0: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  nnections.** wit
a5b0: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f  hin the same pro
a5c0: 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d  cess.  The argum
a5d0: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
a5e0: 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20   to an array of 
a5f0: 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20  two.** integers 
a600: 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20  where the first 
a610: 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 6e  integer is the n
a620: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61  ew retry count a
a630: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  nd the second.**
a640: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20   integer is the 
a650: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65  delay.  If eithe
a660: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67  r integer is neg
a670: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
a680: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f  setting.** is no
a690: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e  t changed but in
a6a0: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20  stead the prior 
a6b0: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65  value of that se
a6c0: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  tting is written
a6d0: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72  .** into the arr
a6e0: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69  ay entry, allowi
a6f0: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  ng the current r
a700: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f  etry settings to
a710: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61   be.** interroga
a720: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d  ted.  The zDbNam
a730: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  e parameter is i
a740: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  gnored..**.** <l
a750: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a760: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a  _PERSIST_WAL]].*
a770: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a780: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
a790: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
a7a0: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
a7b0: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
a7c0: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20  nt [WAL | Write 
a7d0: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69  Ahead Log] setti
a7e0: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ng.  By default,
a7f0: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a   the auxiliary.*
a800: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f  * write ahead lo
a810: 67 20 28 5b 57 41 4c 20 66 69 6c 65 5d 29 20 61  g ([WAL file]) a
a820: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
a830: 0a 2a 2a 20 66 69 6c 65 73 20 75 73 65 64 20 66  .** files used f
a840: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63  or transaction c
a850: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75  ontrol.** are au
a860: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
a870: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74  ted when the lat
a880: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  est connection t
a890: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
a8a0: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69  * closes.  Setti
a8b0: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  ng persistent WA
a8c0: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68  L mode causes th
a8d0: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72  ose files to per
a8e0: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c  sist after.** cl
a8f0: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67  ose.  Persisting
a900: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73   the files is us
a910: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20  eful when other 
a920: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64  processes that d
a930: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72  o not.** have wr
a940: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f  ite permission o
a950: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20  n the directory 
a960: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64  containing the d
a970: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e  atabase file wan
a980: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65  t.** to read the
a990: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
a9a0: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73  as the WAL and s
a9b0: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
a9c0: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a  es must exist.**
a9d0: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68   in order for th
a9e0: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65  e database to be
a9f0: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
aa00: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
aa10: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
aa20: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
aa30: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
aa40: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
aa50: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
aa60: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
aa70: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
aa80: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  le persistent WA
aa90: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  L mode or 1 to e
aaa0: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  nable persistent
aab0: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49  .** WAL mode.  I
aac0: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
aad0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
aae0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
aaf0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
ab00: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20  WAL persistence 
ab10: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
ab20: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ab30: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
ab40: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
ab50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
ab60: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
ab70: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
ab80: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
ab90: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
aba0: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f  ent "powersafe-o
abb0: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53  verwrite" or "PS
abc0: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68  OW" setting.  Th
abd0: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a  e PSOW setting.*
abe0: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  * determines the
abf0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
ac00: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
ac10: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a  TE] bit of the.*
ac20: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  * xDeviceCharact
ac30: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73  eristics methods
ac40: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  . The fourth par
ac50: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
ac60: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
ac70: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
ac80: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
ac90: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
aca0: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
acb0: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
acc0: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61   disable zero-da
acd0: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74  mage mode or 1 t
ace0: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61  o enable zero-da
acf0: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49  mage.** mode.  I
ad00: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
ad10: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
ad20: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
ad30: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
ad40: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
ad50: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
ad60: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
ad70: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  TL_OVERWRITE]].*
ad80: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
ad90: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20  CNTL_OVERWRITE] 
ada0: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65  opcode is invoke
adb0: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65  d by SQLite afte
adc0: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77  r opening.** a w
add0: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  rite transaction
ade0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
adf0: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20  t, unless it is 
ae00: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20  rolled back for 
ae10: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20  some.** reason, 
ae20: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  the entire datab
ae30: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  ase file will be
ae40: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
ae50: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
ae60: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
ae70: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43  s is used by VAC
ae80: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  UUM operations..
ae90: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
aea0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
aeb0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
aec0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
aed0: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
aee0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
aef0: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61  he names of.** a
af00: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68  ll [VFSes] in th
af10: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68  e VFS stack.  Th
af20: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61  e names are of a
af30: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64  ll VFS shims and
af40: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f   the.** final bo
af50: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61  ttom-level VFS a
af60: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  re written into 
af70: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
af80: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
af90: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
afa0: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74  the result is st
afb0: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72  ored in the char
afc0: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68  * variable.** th
afd0: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  at the fourth pa
afe0: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69  rameter of [sqli
aff0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
b000: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a  ()] points to..*
b010: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20  * The caller is 
b020: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
b030: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f  freeing the memo
b040: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41  ry when done.  A
b050: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69  s with.** all fi
b060: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f  le-control actio
b070: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ns, there is no 
b080: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
b090: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c  his will actuall
b0a0: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67  y.** do anything
b0b0: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c  .  Callers shoul
b0c0: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  d initialize the
b0d0: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20   char* variable 
b0e0: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  to a NULL.** poi
b0f0: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69  nter in case thi
b100: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
b110: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
b120: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f  d.  This file-co
b130: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65  ntrol.** is inte
b140: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73  nded for diagnos
b150: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a  tic use only..**
b160: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b170: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
b180: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ER]].** ^The [SQ
b190: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
b1a0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 66  OINTER] opcode f
b1b0: 69 6e 64 73 20 61 20 70 6f 69 6e 74 65 72 20 74  inds a pointer t
b1c0: 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a  o the top-level.
b1d0: 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75 72 72 65  ** [VFSes] curre
b1e0: 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e 28  ntly in use.  ^(
b1f0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20 69  The argument X i
b200: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c  n.** sqlite3_fil
b210: 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c  e_control(db,SQL
b220: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
b230: 49 4e 54 45 52 2c 58 29 20 6d 75 73 74 20 62 65  INTER,X) must be
b240: 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b 73 71  .** of type "[sq
b250: 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20  lite3_vfs] **". 
b260: 20 54 68 69 73 20 6f 70 63 6f 64 65 73 20 77 69   This opcodes wi
b270: 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20  ll set *X.** to 
b280: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
b290: 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29   top-level VFS.)
b2a0: 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72 65  ^.** ^When there
b2b0: 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 20 56 46   are multiple VF
b2c0: 53 20 73 68 69 6d 73 20 69 6e 20 74 68 65 20 73  S shims in the s
b2d0: 74 61 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64  tack, this opcod
b2e0: 65 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75  e finds the.** u
b2f0: 70 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f  pper-most shim o
b300: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
b310: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b320: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
b330: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
b340: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
b350: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
b360: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
b370: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
b380: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
b390: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
b3a0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
b3b0: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
b3c0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
b3d0: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
b3e0: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
b3f0: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
b400: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
b410: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b420: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
b430: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
b440: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
b450: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
b460: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
b470: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
b480: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
b490: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
b4a0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
b4b0: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
b4c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
b4d0: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
b4e0: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
b4f0: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
b500: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
b510: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
b520: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
b530: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
b540: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
b550: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
b560: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
b570: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
b580: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
b590: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
b5a0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
b5b0: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
b5c0: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
b5d0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
b5e0: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
b5f0: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
b600: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
b610: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
b620: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
b630: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
b640: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
b650: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
b660: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
b670: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
b680: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
b690: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
b6a0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
b6b0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
b6c0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
b6d0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
b6e0: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
b6f0: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
b700: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
b710: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
b720: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
b730: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
b740: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
b750: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
b760: 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e   if result strin
b770: 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68  g is NULL, or th
b780: 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  at returns a cop
b790: 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  y.** of the resu
b7a0: 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65  lt string if the
b7b0: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e   string is non-N
b7c0: 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ULL..** ^If the 
b7d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b7e0: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
b7f0: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ol returns.** an
b800: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74  y result code ot
b810: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
b820: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  _OK] or [SQLITE_
b830: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20  NOTFOUND], that 
b840: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68  means.** that th
b850: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65  e VFS encountere
b860: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65  d an error while
b870: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50   handling the [P
b880: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a  RAGMA] and the.*
b890: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66  * compilation of
b8a0: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c   the PRAGMA fail
b8b0: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  s with an error.
b8c0: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46    ^The [SQLITE_F
b8d0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
b8e0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63  file control occ
b8f0: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e  urs at the begin
b900: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73  ning of pragma s
b910: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69  tatement analysi
b920: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69  s and so.** it i
b930: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69  s able to overri
b940: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41  de built-in [PRA
b950: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  GMA] statements.
b960: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b970: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b980: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  NDLER]].** ^The 
b990: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
b9a0: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69  SYHANDLER].** fi
b9b0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62  le-control may b
b9c0: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  e invoked by SQL
b9d0: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ite on the datab
b9e0: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a  ase file handle.
b9f0: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72  ** shortly after
ba00: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e   it is opened in
ba10: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
ba20: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77  e a custom VFS w
ba30: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ith access.** to
ba40: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
ba50: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61   busy-handler ca
ba60: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75  llback. The argu
ba70: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20  ment is of type 
ba80: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61  (void **).** - a
ba90: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28  n array of two (
baa0: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20  void *) values. 
bab0: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20  The first (void 
bac0: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e  *) actually poin
bad0: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74  ts.** to a funct
bae0: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74  ion of type (int
baf0: 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49   (*)(void *)). I
bb00: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b  n order to invok
bb10: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  e the connection
bb20: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65  s.** busy-handle
bb30: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  r, this function
bb40: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b   should be invok
bb50: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f  ed with the seco
bb60: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a  nd (void *) in.*
bb70: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74  * the array as t
bb80: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  he only argument
bb90: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
bba0: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
bbb0: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
bbc0: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65  should be retrie
bbd0: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  d. If it returns
bbe0: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f   zero, the custo
bbf0: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61  m VFS should aba
bc00: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  ndon the.** curr
bc10: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a  ent operation..*
bc20: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
bc30: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
bc40: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69  NAME]].** ^Appli
bc50: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b  cation can invok
bc60: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  e the [SQLITE_FC
bc70: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
bc80: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  ] file-control.*
bc90: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65  * to have SQLite
bca0: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74   generate a.** t
bcb0: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
bcc0: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
bcd0: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20   algorithm that 
bce0: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67  is followed to g
bcf0: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  enerate.** tempo
bd00: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66  rary filenames f
bd10: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61  or TEMP tables a
bd20: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61  nd other interna
bd30: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20  l uses.  The.** 
bd40: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
bd50: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63  be a char** whic
bd60: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64  h will be filled
bd70: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61   with the filena
bd80: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e  me.** written in
bd90: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
bda0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
bdb0: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
bdc0: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a   caller should.*
bdd0: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  * invoke [sqlite
bde0: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65  3_free()] on the
bdf0: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64   result to avoid
be00: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a   a memory leak..
be10: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
be20: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
be30: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
be40: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
be50: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
be60: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65  l is used to que
be70: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a  ry or set the.**
be80: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
be90: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69  of bytes that wi
bea0: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d  ll be used for m
beb0: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f  emory-mapped I/O
bec0: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
bed0: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
bee0: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70  o a value of typ
bef0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
bf00: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64  that.** is an ad
bf10: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e  visory maximum n
bf20: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
bf30: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65  n the file to me
bf40: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a  mory map.  The.*
bf50: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65  * pointer is ove
bf60: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
bf70: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68  e old value.  Th
bf80: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  e limit is not c
bf90: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65  hanged if.** the
bfa0: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c   value originall
bfb0: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20  y pointed to is 
bfc0: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f  negative, and so
bfd0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d   the current lim
bfe0: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75  it .** can be qu
bff0: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67  eried by passing
c000: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   in a pointer to
c010: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
c020: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c  er.  This.** fil
c030: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e-control is use
c040: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
c050: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d  implement [PRAGM
c060: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a  A mmap_size]..**
c070: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
c080: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a  _FCNTL_TRACE]].*
c090: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c0a0: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20  NTL_TRACE] file 
c0b0: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73  control provides
c0c0: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d   advisory inform
c0d0: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20  ation.** to the 
c0e0: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74  VFS about what t
c0f0: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73  he higher layers
c100: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73   of the SQLite s
c110: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a  tack are doing..
c120: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
c130: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20  trol is used by 
c140: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74  some VFS activit
c150: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73  y tracing [shims
c160: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  ]..** The argume
c170: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72  nt is a zero-ter
c180: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20  minated string. 
c190: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69   Higher layers i
c1a0: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  n the.** SQLite 
c1b0: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61  stack may genera
c1c0: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20  te instances of 
c1d0: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  this file contro
c1e0: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  l if.** the [SQL
c1f0: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52  ITE_USE_FCNTL_TR
c200: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
c210: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
c220: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  led..**.** <li>[
c230: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
c240: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65  S_MOVED]].** The
c250: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48   [SQLITE_FCNTL_H
c260: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63  AS_MOVED] file c
c270: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
c280: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
c290: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
c2a0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
c2b0: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f   it writes a boo
c2c0: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69  lean into that i
c2d0: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67  nteger depending
c2e0: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f  .** on whether o
c2f0: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68  r not the file h
c300: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c  as been renamed,
c310: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74   moved, or delet
c320: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77  ed since it.** w
c330: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e  as first opened.
c340: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c350: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
c360: 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  GET_HANDLE]].** 
c370: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c380: 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44  L_WIN32_GET_HAND
c390: 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62  LE] opcode can b
c3a0: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
c3b0: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
c3c0: 6e 67 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68  ng native file h
c3d0: 61 6e 64 6c 65 20 61 73 73 6f 63 69 61 74 65 64  andle associated
c3e0: 20 77 69 74 68 20 61 20 66 69 6c 65 20 68 61 6e   with a file han
c3f0: 64 6c 65 2e 20 20 54 68 69 73 20 66 69 6c 65 0a  dle.  This file.
c400: 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72  ** control inter
c410: 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65  prets its argume
c420: 6e 74 20 61 73 20 61 20 70 6f 69 6e 74 65 72 20  nt as a pointer 
c430: 74 6f 20 61 20 6e 61 74 69 76 65 20 66 69 6c 65  to a native file
c440: 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a 2a 20 77   handle and.** w
c450: 72 69 74 65 73 20 74 68 65 20 72 65 73 75 6c 74  rites the result
c460: 69 6e 67 20 76 61 6c 75 65 20 74 68 65 72 65 2e  ing value there.
c470: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c480: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
c490: 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  SET_HANDLE]].** 
c4a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c4b0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
c4c0: 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  LE] opcode is us
c4d0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
c4e0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
c4f0: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
c500: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
c510: 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c   to swap the fil
c520: 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68  e handle with th
c530: 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64  e one.** pointed
c540: 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20   to by the pArg 
c550: 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20  argument.  This 
c560: 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73  capability is us
c570: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
c580: 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  g.** and only ne
c590: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
c5a0: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
c5b0: 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e  TEST is defined.
c5c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c5d0: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
c5e0: 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  OCK]].** The [SQ
c5f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
c600: 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61  LOCK] is a signa
c610: 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79  l to the VFS lay
c620: 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  er that it might
c630: 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65  .** be advantage
c640: 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20  ous to block on 
c650: 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63  the next WAL loc
c660: 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73  k if the lock is
c670: 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79   not immediately
c680: 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20  .** available.  
c690: 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65  The WAL subsyste
c6a0: 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69  m issues this si
c6b0: 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65  gnal during rare
c6c0: 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65  .** circumstance
c6d0: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  s in order to fi
c6e0: 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68  x a problem with
c6f0: 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73   priority invers
c700: 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ion..** Applicat
c710: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e  ions should <em>
c720: 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69  not</em> use thi
c730: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a  s file-control..
c740: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c750: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d  TE_FCNTL_ZIPVFS]
c760: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
c770: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f  _FCNTL_ZIPVFS] o
c780: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65  pcode is impleme
c790: 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f  nted by zipvfs o
c7a0: 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a  nly. All other.*
c7b0: 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74  * VFS should ret
c7c0: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  urn SQLITE_NOTFO
c7d0: 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63  UND for this opc
c7e0: 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ode..**.** <li>[
c7f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42  [SQLITE_FCNTL_RB
c800: 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  U]].** The [SQLI
c810: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70  TE_FCNTL_RBU] op
c820: 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  code is implemen
c830: 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63 69  ted by the speci
c840: 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a  al VFS used by.*
c850: 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e 73  * the RBU extens
c860: 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f  ion only.  All o
c870: 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20  ther VFS should 
c880: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
c890: 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68  TFOUND for.** th
c8a0: 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 0a  is opcode.  .**.
c8b0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c8c0: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
c8d0: 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 49 66  IC_WRITE]].** If
c8e0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
c8f0: 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f  TL_BEGIN_ATOMIC_
c900: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 72 65  WRITE] opcode re
c910: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2c  turns SQLITE_OK,
c920: 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 66 69 6c   then.** the fil
c930: 65 20 64 65 73 63 72 69 70 74 6f 72 20 69 73 20  e descriptor is 
c940: 70 6c 61 63 65 64 20 69 6e 20 22 62 61 74 63 68  placed in "batch
c950: 20 77 72 69 74 65 20 6d 6f 64 65 22 2c 20 77 68   write mode", wh
c960: 69 63 68 0a 2a 2a 20 6d 65 61 6e 73 20 61 6c 6c  ich.** means all
c970: 20 73 75 62 73 65 71 75 65 6e 74 20 77 72 69 74   subsequent writ
c980: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 69 6c  e operations wil
c990: 6c 20 62 65 20 64 65 66 65 72 72 65 64 20 61 6e  l be deferred an
c9a0: 64 20 64 6f 6e 65 0a 2a 2a 20 61 74 6f 6d 69 63  d done.** atomic
c9b0: 61 6c 6c 79 20 61 74 20 74 68 65 20 6e 65 78 74  ally at the next
c9c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
c9d0: 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49  OMMIT_ATOMIC_WRI
c9e0: 54 45 5d 2e 20 20 53 79 73 74 65 6d 73 0a 2a 2a  TE].  Systems.**
c9f0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 73 75 70   that do not sup
ca00: 70 6f 72 74 20 62 61 74 63 68 20 61 74 6f 6d 69  port batch atomi
ca10: 63 20 77 72 69 74 65 73 20 77 69 6c 6c 20 72 65  c writes will re
ca20: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46  turn SQLITE_NOTF
ca30: 4f 55 4e 44 2e 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77  OUND..** ^Follow
ca40: 69 6e 67 20 61 20 73 75 63 63 65 73 73 66 75 6c  ing a successful
ca50: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45   SQLITE_FCNTL_BE
ca60: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
ca70: 20 61 6e 64 20 70 72 69 6f 72 20 74 6f 0a 2a 2a   and prior to.**
ca80: 20 74 68 65 20 63 6c 6f 73 69 6e 67 20 5b 53 51   the closing [SQ
ca90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
caa0: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  T_ATOMIC_WRITE] 
cab0: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  or.** [SQLITE_FC
cac0: 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f  NTL_ROLLBACK_ATO
cad0: 4d 49 43 5f 57 52 49 54 45 5d 2c 20 53 51 4c 69  MIC_WRITE], SQLi
cae0: 74 65 20 77 69 6c 6c 20 6d 61 6b 65 0a 2a 2a 20  te will make.** 
caf0: 6e 6f 20 56 46 53 20 69 6e 74 65 72 66 61 63 65  no VFS interface
cb00: 20 63 61 6c 6c 73 20 6f 6e 20 74 68 65 20 73 61   calls on the sa
cb10: 6d 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  me [sqlite3_file
cb20: 5d 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  ] file descripto
cb30: 72 0a 2a 2a 20 65 78 63 65 70 74 20 66 6f 72 20  r.** except for 
cb40: 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 78 57 72  calls to the xWr
cb50: 69 74 65 20 6d 65 74 68 6f 64 20 61 6e 64 20 74  ite method and t
cb60: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
cb70: 6d 65 74 68 6f 64 0a 2a 2a 20 77 69 74 68 20 5b  method.** with [
cb80: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
cb90: 45 5f 48 49 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  E_HINT]..**.** <
cba0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
cbb0: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
cbc0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  WRITE]].** The [
cbd0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
cbe0: 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  MIT_ATOMIC_WRITE
cbf0: 5d 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  ] opcode causes 
cc00: 61 6c 6c 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65  all write.** ope
cc10: 72 61 74 69 6f 6e 73 20 73 69 6e 63 65 20 74 68  rations since th
cc20: 65 20 70 72 65 76 69 6f 75 73 20 73 75 63 63 65  e previous succe
cc30: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a  ssful call to .*
cc40: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
cc50: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49  BEGIN_ATOMIC_WRI
cc60: 54 45 5d 20 74 6f 20 62 65 20 70 65 72 66 6f 72  TE] to be perfor
cc70: 6d 65 64 20 61 74 6f 6d 69 63 61 6c 6c 79 2e 0a  med atomically..
cc80: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
cc90: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
cca0: 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61 6e 64 20  LITE_OK] if and 
ccb0: 6f 6e 6c 79 20 69 66 20 74 68 65 20 77 72 69 74  only if the writ
ccc0: 65 73 20 77 65 72 65 0a 2a 2a 20 61 6c 6c 20 70  es were.** all p
ccd0: 65 72 66 6f 72 6d 65 64 20 73 75 63 63 65 73 73  erformed success
cce0: 66 75 6c 6c 79 20 61 6e 64 20 68 61 76 65 20 62  fully and have b
ccf0: 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 74 6f  een committed to
cd00: 20 70 65 72 73 69 73 74 65 6e 74 20 73 74 6f 72   persistent stor
cd10: 61 67 65 2e 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  age..** ^Regardl
cd20: 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
cd30: 72 20 6e 6f 74 20 69 74 20 69 73 20 73 75 63 63  r not it is succ
cd40: 65 73 73 66 75 6c 2c 20 74 68 69 73 20 66 69 6c  essful, this fil
cd50: 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 0a  e control takes.
cd60: 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73 63  ** the file desc
cd70: 72 69 70 74 6f 72 20 6f 75 74 20 6f 66 20 62 61  riptor out of ba
cd80: 74 63 68 20 77 72 69 74 65 20 6d 6f 64 65 20 73  tch write mode s
cd90: 6f 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65  o that all subse
cda0: 71 75 65 6e 74 0a 2a 2a 20 77 72 69 74 65 20 6f  quent.** write o
cdb0: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 69 6e  perations are in
cdc0: 64 65 70 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53  dependent..** ^S
cdd0: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
cde0: 20 69 6e 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46   invoke SQLITE_F
cdf0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d  CNTL_COMMIT_ATOM
ce00: 49 43 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74  IC_WRITE without
ce10: 0a 2a 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63  .** a prior succ
ce20: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
ce30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
ce40: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
ce50: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
ce60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42  LITE_FCNTL_ROLLB
ce70: 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  ACK_ATOMIC_WRITE
ce80: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
ce90: 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b  E_FCNTL_ROLLBACK
cea0: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f  _ATOMIC_WRITE] o
ceb0: 70 63 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c  pcode causes all
cec0: 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74   write.** operat
ced0: 69 6f 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70  ions since the p
cee0: 72 65 76 69 6f 75 73 20 73 75 63 63 65 73 73 66  revious successf
cef0: 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b  ul call to .** [
cf00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
cf10: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
cf20: 20 74 6f 20 62 65 20 72 6f 6c 6c 65 64 20 62 61   to be rolled ba
cf30: 63 6b 2e 0a 2a 2a 20 5e 54 68 69 73 20 66 69 6c  ck..** ^This fil
cf40: 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 20  e control takes 
cf50: 74 68 65 20 66 69 6c 65 20 64 65 73 63 72 69 70  the file descrip
cf60: 74 6f 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68  tor out of batch
cf70: 20 77 72 69 74 65 20 6d 6f 64 65 0a 2a 2a 20 73   write mode.** s
cf80: 6f 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65  o that all subse
cf90: 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65 72  quent write oper
cfa0: 61 74 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70  ations are indep
cfb0: 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69  endent..** ^SQLi
cfc0: 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e  te will never in
cfd0: 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  voke SQLITE_FCNT
cfe0: 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49  L_ROLLBACK_ATOMI
cff0: 43 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74 0a  C_WRITE without.
d000: 2a 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63 65  ** a prior succe
d010: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53  ssful call to [S
d020: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
d030: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e  N_ATOMIC_WRITE].
d040: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
d050: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54  ITE_FCNTL_LOCK_T
d060: 49 4d 45 4f 55 54 5d 5d 0a 2a 2a 20 54 68 65 20  IMEOUT]].** The 
d070: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
d080: 43 4b 5f 54 49 4d 45 4f 55 54 5d 20 6f 70 63 6f  CK_TIMEOUT] opco
d090: 64 65 20 63 61 75 73 65 73 20 61 74 74 65 6d 70  de causes attemp
d0a0: 74 73 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ts to obtain.** 
d0b0: 61 20 66 69 6c 65 20 6c 6f 63 6b 20 75 73 69 6e  a file lock usin
d0c0: 67 20 74 68 65 20 78 4c 6f 63 6b 20 6f 72 20 78  g the xLock or x
d0d0: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 73 20  ShmLock methods 
d0e0: 6f 66 20 74 68 65 20 56 46 53 20 74 6f 20 77 61  of the VFS to wa
d0f0: 69 74 0a 2a 2a 20 66 6f 72 20 75 70 20 74 6f 20  it.** for up to 
d100: 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62  M milliseconds b
d110: 65 66 6f 72 65 20 66 61 69 6c 69 6e 67 2c 20 77  efore failing, w
d120: 68 65 72 65 20 4d 20 69 73 20 74 68 65 20 73 69  here M is the si
d130: 6e 67 6c 65 20 0a 2a 2a 20 75 6e 73 69 67 6e 65  ngle .** unsigne
d140: 64 20 69 6e 74 65 67 65 72 20 70 61 72 61 6d 65  d integer parame
d150: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ter..**.** <li>[
d160: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41  [SQLITE_FCNTL_DA
d170: 54 41 5f 56 45 52 53 49 4f 4e 5d 5d 0a 2a 2a 20  TA_VERSION]].** 
d180: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
d190: 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 5d 20  L_DATA_VERSION] 
d1a0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
d1b0: 6f 20 64 65 74 65 63 74 20 63 68 61 6e 67 65 73  o detect changes
d1c0: 20 74 6f 0a 2a 2a 20 61 20 64 61 74 61 62 61 73   to.** a databas
d1d0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 61 72 67  e file.  The arg
d1e0: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
d1f0: 65 72 20 74 6f 20 61 20 33 32 2d 62 69 74 20 75  er to a 32-bit u
d200: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e  nsigned integer.
d210: 0a 2a 2a 20 54 68 65 20 22 64 61 74 61 20 76 65  .** The "data ve
d220: 72 73 69 6f 6e 22 20 66 6f 72 20 74 68 65 20 70  rsion" for the p
d230: 61 67 65 72 20 69 73 20 77 72 69 74 74 65 6e 20  ager is written 
d240: 69 6e 74 6f 20 74 68 65 20 70 6f 69 6e 74 65 72  into the pointer
d250: 2e 20 20 54 68 65 0a 2a 2a 20 22 64 61 74 61 20  .  The.** "data 
d260: 76 65 72 73 69 6f 6e 22 20 63 68 61 6e 67 65 73  version" changes
d270: 20 77 68 65 6e 65 76 65 72 20 61 6e 79 20 63 68   whenever any ch
d280: 61 6e 67 65 20 6f 63 63 75 72 73 20 74 6f 20 74  ange occurs to t
d290: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
d2a0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c  .** database fil
d2b0: 65 2c 20 65 69 74 68 65 72 20 74 68 72 6f 75 67  e, either throug
d2c0: 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  h SQL statements
d2d0: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
d2e0: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
d2f0: 69 6f 6e 20 6f 72 20 74 68 72 6f 75 67 68 20 74  ion or through t
d300: 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 6f 6d 6d  ransactions comm
d310: 69 74 74 65 64 20 62 79 20 73 65 70 61 72 61 74  itted by separat
d320: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
d330: 6e 6e 65 63 74 69 6f 6e 73 20 70 6f 73 73 69 62  nnections possib
d340: 6c 79 20 69 6e 20 6f 74 68 65 72 20 70 72 6f 63  ly in other proc
d350: 65 73 73 65 73 2e 20 54 68 65 20 5b 73 71 6c 69  esses. The [sqli
d360: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
d370: 73 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  s()].** interfac
d380: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
d390: 20 66 69 6e 64 20 69 66 20 61 6e 79 20 64 61 74   find if any dat
d3a0: 61 62 61 73 65 20 6f 6e 20 74 68 65 20 63 6f 6e  abase on the con
d3b0: 6e 65 63 74 69 6f 6e 20 68 61 73 20 63 68 61 6e  nection has chan
d3c0: 67 65 64 2c 0a 2a 2a 20 62 75 74 20 74 68 61 74  ged,.** but that
d3d0: 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 70 6f   interface respo
d3e0: 6e 64 73 20 74 6f 20 63 68 61 6e 67 65 73 20 6f  nds to changes o
d3f0: 6e 20 54 45 4d 50 20 61 73 20 77 65 6c 6c 20 61  n TEMP as well a
d400: 73 20 4d 41 49 4e 20 61 6e 64 20 64 6f 65 73 0a  s MAIN and does.
d410: 2a 2a 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61  ** not provide a
d420: 20 6d 65 63 68 61 6e 69 73 6d 20 74 6f 20 64 65   mechanism to de
d430: 74 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 20  tect changes to 
d440: 4d 41 49 4e 20 6f 6e 6c 79 2e 20 20 41 6c 73 6f  MAIN only.  Also
d450: 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
d460: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
d470: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
d480: 70 6f 6e 64 73 20 74 6f 20 69 6e 74 65 72 6e 61  ponds to interna
d490: 6c 20 63 68 61 6e 67 65 73 20 6f 6e 6c 79 20 61  l changes only a
d4a0: 6e 64 0a 2a 2a 20 6f 6d 69 74 73 20 63 68 61 6e  nd.** omits chan
d4b0: 67 65 73 20 6d 61 64 65 20 62 79 20 6f 74 68 65  ges made by othe
d4c0: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
d4d0: 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
d4e0: 5b 50 52 41 47 4d 41 20 64 61 74 61 5f 76 65 72  [PRAGMA data_ver
d4f0: 73 69 6f 6e 5d 20 63 6f 6d 6d 61 6e 64 20 70 72  sion] command pr
d500: 6f 76 69 64 65 20 61 20 6d 65 63 68 61 6e 69 73  ovide a mechanis
d510: 6d 20 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e  m to detect chan
d520: 67 65 73 20 74 6f 0a 2a 2a 20 61 20 73 69 6e 67  ges to.** a sing
d530: 6c 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  le attached data
d540: 62 61 73 65 20 74 68 61 74 20 6f 63 63 75 72 20  base that occur 
d550: 64 75 65 20 74 6f 20 6f 74 68 65 72 20 64 61 74  due to other dat
d560: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d570: 73 2c 0a 2a 2a 20 62 75 74 20 6f 6d 69 74 73 20  s,.** but omits 
d580: 63 68 61 6e 67 65 73 20 69 6d 70 6c 65 6d 65 6e  changes implemen
d590: 74 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62  ted by the datab
d5a0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
d5b0: 6e 20 77 68 69 63 68 20 69 74 20 69 73 0a 2a 2a  n which it is.**
d5c0: 20 63 61 6c 6c 65 64 2e 20 20 54 68 69 73 20 66   called.  This f
d5d0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 74  ile control is t
d5e0: 68 65 20 6f 6e 6c 79 20 6d 65 63 68 61 6e 69 73  he only mechanis
d5f0: 6d 20 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e  m to detect chan
d600: 67 65 73 20 74 68 61 74 0a 2a 2a 20 68 61 70 70  ges that.** happ
d610: 65 6e 20 65 69 74 68 65 72 20 69 6e 74 65 72 6e  en either intern
d620: 61 6c 6c 79 20 6f 72 20 65 78 74 65 72 6e 61 6c  ally or external
d630: 6c 79 20 61 6e 64 20 74 68 61 74 20 61 72 65 20  ly and that are 
d640: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
d650: 2a 2a 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ** a particular 
d660: 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
d670: 65 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23  e..** </ul>.*/.#
d680: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d690: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
d6a0: 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
d6b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d6c0: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
d6d0: 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65  FILE       2.#de
d6e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d6f0: 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_SET_LOCKPROXYF
d700: 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65 66  ILE       3.#def
d710: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d720: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
d730: 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
d740: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d750: 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20  SIZE_HINT       
d760: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
d770: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
d780: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20  HUNK_SIZE       
d790: 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
d7a0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49   SQLITE_FCNTL_FI
d7b0: 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  LE_POINTER      
d7c0: 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
d7d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
d7e0: 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20  C_OMITTED       
d7f0: 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
d800: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
d810: 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20  2_AV_RETRY      
d820: 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
d830: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
d840: 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  ST_WAL          
d850: 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
d860: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
d870: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
d880: 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   11.#define SQLI
d890: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
d8a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d8b0: 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  12.#define SQLIT
d8c0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
d8d0: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31  E_OVERWRITE    1
d8e0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
d8f0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20  _FCNTL_PRAGMA   
d900: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34                14
d910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d920: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
d930: 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a  R            15.
d940: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d950: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
d960: 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23  E           16.#
d970: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d980: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20  NTL_MMAP_SIZE   
d990: 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64             18.#d
d9a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d9b0: 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20  TL_TRACE        
d9c0: 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 65            19.#de
d9d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d9e0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20  L_HAS_MOVED     
d9f0: 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 66           20.#def
da00: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
da10: 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  _SYNC           
da20: 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 69          21.#defi
da30: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
da40: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20  COMMIT_PHASETWO 
da50: 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e         22.#defin
da60: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
da70: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20  IN32_SET_HANDLE 
da80: 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65        23.#define
da90: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41   SQLITE_FCNTL_WA
daa0: 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  L_BLOCK         
dab0: 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20       24.#define 
dac0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50  SQLITE_FCNTL_ZIP
dad0: 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20 20  VFS             
dae0: 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20 53      25.#define S
daf0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20  QLITE_FCNTL_RBU 
db00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
db10: 20 20 20 32 36 0a 23 64 65 66 69 6e 65 20 53 51     26.#define SQ
db20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
db30: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20  OINTER          
db40: 20 20 32 37 0a 23 64 65 66 69 6e 65 20 53 51 4c    27.#define SQL
db50: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
db60: 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  L_POINTER       
db70: 20 32 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   28.#define SQLI
db80: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47  TE_FCNTL_WIN32_G
db90: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
dba0: 32 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  29.#define SQLIT
dbb0: 45 5f 46 43 4e 54 4c 5f 50 44 42 20 20 20 20 20  E_FCNTL_PDB     
dbc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
dbd0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
dbe0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
dbf0: 4d 49 43 5f 57 52 49 54 45 20 20 20 20 20 33 31  MIC_WRITE     31
dc00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dc10: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
dc20: 4d 49 43 5f 57 52 49 54 45 20 20 20 20 33 32 0a  MIC_WRITE    32.
dc30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
dc40: 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54  CNTL_ROLLBACK_AT
dc50: 4f 4d 49 43 5f 57 52 49 54 45 20 20 33 33 0a 23  OMIC_WRITE  33.#
dc60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
dc70: 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54  NTL_LOCK_TIMEOUT
dc80: 20 20 20 20 20 20 20 20 20 20 20 33 34 0a 23 64             34.#d
dc90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
dca0: 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 20  TL_DATA_VERSION 
dcb0: 20 20 20 20 20 20 20 20 20 20 33 35 0a 23 64 65            35.#de
dcc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
dcd0: 4c 5f 53 49 5a 45 5f 4c 49 4d 49 54 20 20 20 20  L_SIZE_LIMIT    
dce0: 20 20 20 20 20 20 20 20 20 33 36 0a 0a 2f 2a 20           36../* 
dcf0: 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73  deprecated names
dd00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
dd10: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
dd20: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45  FILE      SQLITE
dd30: 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50  _FCNTL_GET_LOCKP
dd40: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65  ROXYFILE.#define
dd50: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
dd60: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53  PROXYFILE      S
dd70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
dd80: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64  LOCKPROXYFILE.#d
dd90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53  efine SQLITE_LAS
dda0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
ddb0: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
ddc0: 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a  _LAST_ERRNO.../*
ddd0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
dde0: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  tex Handle.**.**
ddf0: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
de00: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
de10: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
de20: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
de30: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
de40: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
de50: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
de60: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
de70: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
de80: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
de90: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
dea0: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
deb0: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
dec0: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
ded0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
dee0: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
def0: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
df00: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
df10: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
df20: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
df30: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
df40: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
df50: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
df60: 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20 45 78 74  EF: Loadable Ext
df70: 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a  ension Thunk.**.
df80: 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
df90: 74 68 65 20 6f 70 61 71 75 65 20 73 71 6c 69 74  the opaque sqlit
dfa0: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20  e3_api_routines 
dfb0: 73 74 72 75 63 74 75 72 65 20 69 73 20 70 61 73  structure is pas
dfc0: 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 74 68  sed as.** the th
dfd0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
dfe0: 20 65 6e 74 72 79 20 70 6f 69 6e 74 73 20 6f 66   entry points of
dff0: 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e   [loadable exten
e000: 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a  sions].  This.**
e010: 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20   structure must 
e020: 62 65 20 74 79 70 65 64 65 66 65 64 20 69 6e 20  be typedefed in 
e030: 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 61 72  order to work ar
e040: 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72 20 77 61  ound compiler wa
e050: 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d  rnings.** on som
e060: 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a  e platforms..*/.
e070: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
e080: 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69  qlite3_api_routi
e090: 6e 65 73 20 73 71 6c 69 74 65 33 5f 61 70 69 5f  nes sqlite3_api_
e0a0: 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a  routines;../*.**
e0b0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
e0c0: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a  terface Object.*
e0d0: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
e0e0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
e0f0: 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  vfs object defin
e100: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
e110: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
e120: 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20  SQLite core and 
e130: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f  the underlying o
e140: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
e150: 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69    The "vfs".** i
e160: 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
e170: 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20  e object stands 
e180: 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c  for "virtual fil
e190: 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a  e system".  See.
e1a0: 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46  ** the [VFS | VF
e1b0: 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  S documentation]
e1c0: 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66   for further inf
e1d0: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
e1e0: 54 68 65 20 56 46 53 20 69 6e 74 65 72 66 61 63  The VFS interfac
e1f0: 65 20 69 73 20 73 6f 6d 65 74 69 6d 65 73 20 65  e is sometimes e
e200: 78 74 65 6e 64 65 64 20 62 79 20 61 64 64 69 6e  xtended by addin
e210: 67 20 6e 65 77 20 6d 65 74 68 6f 64 73 20 6f 6e  g new methods on
e220: 74 6f 0a 2a 2a 20 74 68 65 20 65 6e 64 2e 20 20  to.** the end.  
e230: 45 61 63 68 20 74 69 6d 65 20 73 75 63 68 20 61  Each time such a
e240: 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6f 63 63 75  n extension occu
e250: 72 73 2c 20 74 68 65 20 69 56 65 72 73 69 6f 6e  rs, the iVersion
e260: 20 66 69 65 6c 64 0a 2a 2a 20 69 73 20 69 6e 63   field.** is inc
e270: 72 65 6d 65 6e 74 65 64 2e 20 20 54 68 65 20 69  remented.  The i
e280: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 73 74  Version value st
e290: 61 72 74 65 64 20 6f 75 74 20 61 73 20 31 20 69  arted out as 1 i
e2a0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72  n.** SQLite [ver
e2b0: 73 69 6f 6e 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b  sion 3.5.0] on [
e2c0: 64 61 74 65 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74  dateof:3.5.0], t
e2d0: 68 65 6e 20 69 6e 63 72 65 61 73 65 64 20 74 6f  hen increased to
e2e0: 20 32 0a 2a 2a 20 77 69 74 68 20 53 51 4c 69 74   2.** with SQLit
e2f0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37 2e 30  e [version 3.7.0
e300: 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37  ] on [dateof:3.7
e310: 2e 30 5d 2c 20 61 6e 64 20 74 68 65 6e 20 69 6e  .0], and then in
e320: 63 72 65 61 73 65 64 0a 2a 2a 20 74 6f 20 33 20  creased.** to 3 
e330: 77 69 74 68 20 53 51 4c 69 74 65 20 5b 76 65 72  with SQLite [ver
e340: 73 69 6f 6e 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b  sion 3.7.6] on [
e350: 64 61 74 65 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20  dateof:3.7.6].  
e360: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
e370: 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 70 70 65  s.** may be appe
e380: 6e 64 65 64 20 74 6f 20 74 68 65 20 73 71 6c 69  nded to the sqli
e390: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 61  te3_vfs object a
e3a0: 6e 64 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  nd the iVersion 
e3b0: 76 61 6c 75 65 0a 2a 2a 20 6d 61 79 20 69 6e 63  value.** may inc
e3c0: 72 65 61 73 65 20 61 67 61 69 6e 20 69 6e 20 66  rease again in f
e3d0: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
e3e0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74  f SQLite..** Not
e3f0: 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63  e that the struc
e400: 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73  ture.** of the s
e410: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
e420: 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  t changes in the
e430: 20 74 72 61 6e 73 69 74 69 6f 6e 20 66 72 6f 6d   transition from
e440: 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73  .** SQLite [vers
e450: 69 6f 6e 20 33 2e 35 2e 39 5d 20 74 6f 20 5b 76  ion 3.5.9] to [v
e460: 65 72 73 69 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e  ersion 3.6.0] on
e470: 20 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a   [dateof:3.6.0].
e480: 2a 2a 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  ** and yet the i
e490: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
e4a0: 73 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 2e 0a  s not modified..
e4b0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
e4c0: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
e4d0: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
e4e0: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
e4f0: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
e500: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
e510: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
e520: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
e530: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
e540: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
e550: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
e560: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
e570: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
e580: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
e590: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
e5a0: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
e5b0: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
e5c0: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
e5d0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
e5e0: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
e5f0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
e600: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
e610: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
e620: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
e630: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
e640: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
e650: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
e660: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
e670: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
e680: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
e690: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
e6a0: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
e6b0: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
e6c0: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
e6d0: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
e6e0: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
e6f0: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
e700: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
e710: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
e720: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
e730: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
e740: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
e750: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
e760: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
e770: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
e780: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
e790: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
e7a0: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
e7b0: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
e7c0: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
e7d0: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
e7e0: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
e7f0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
e800: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
e810: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
e820: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
e830: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
e840: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
e850: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
e860: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
e870: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
e880: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
e890: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
e8a0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
e8b0: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
e8c0: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
e8d0: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
e8e0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
e8f0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
e900: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
e910: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
e920: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
e930: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
e940: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
e950: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
e960: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
e970: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
e980: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
e990: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c  re than.** 11 al
e9a0: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
e9b0: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
e9c0: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
e9d0: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
e9e0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
e9f0: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
ea00: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
ea10: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
ea20: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
ea30: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
ea40: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
ea50: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
ea60: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
ea70: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
ea80: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
ea90: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
eaa0: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
eab0: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
eac0: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
ead0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
eae0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
eaf0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
eb00: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
eb10: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
eb20: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
eb30: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
eb40: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
eb50: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
eb60: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
eb70: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
eb80: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
eb90: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
eba0: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
ebb0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
ebc0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
ebd0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
ebe0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
ebf0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
ec00: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
ec10: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
ec20: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
ec30: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
ec40: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
ec50: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
ec60: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
ec70: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
ec80: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
ec90: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
eca0: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
ecb0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
ecc0: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
ecd0: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
ece0: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
ecf0: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
ed00: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
ed10: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
ed20: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
ed30: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
ed40: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
ed50: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
ed60: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
ed70: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
ed80: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
ed90: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
eda0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
edb0: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
edc0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
edd0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
ede0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
edf0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ee00: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
ee10: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ee20: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
ee30: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ee40: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
ee50: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
ee60: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
ee70: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
ee80: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
ee90: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
eea0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
eeb0: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
eec0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
eed0: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
eee0: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
eef0: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
ef00: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
ef10: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
ef20: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
ef30: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
ef40: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
ef50: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
ef60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
ef70: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
ef80: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
ef90: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
efa0: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
efb0: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
efc0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
efd0: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
efe0: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
eff0: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
f000: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
f010: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
f020: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
f030: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
f040: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
f050: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
f060: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
f070: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
f080: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
f090: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
f0a0: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
f0b0: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
f0c0: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
f0d0: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
f0e0: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
f0f0: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
f100: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
f110: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
f120: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
f130: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
f140: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
f150: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
f160: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
f170: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
f180: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
f190: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
f1a0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
f1b0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
f1c0: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
f1d0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
f1e0: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
f1f0: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
f200: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
f210: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
f220: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
f230: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
f240: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
f250: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
f260: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
f270: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
f280: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
f290: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
f2a0: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
f2b0: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
f2c0: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
f2d0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
f2e0: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
f2f0: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
f300: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
f310: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
f320: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
f330: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
f340: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
f350: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
f360: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
f370: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
f380: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
f390: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
f3a0: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
f3b0: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
f3c0: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
f3d0: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
f3e0: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
f3f0: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
f400: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
f410: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
f420: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
f430: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
f440: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
f450: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
f460: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
f470: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
f480: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
f490: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
f4a0: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
f4b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
f4c0: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
f4d0: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
f4e0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
f4f0: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
f500: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
f510: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
f520: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
f530: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
f540: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
f550: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
f560: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
f570: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
f580: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
f590: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
f5a0: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
f5b0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
f5c0: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
f5d0: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
f5e0: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
f5f0: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
f600: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
f610: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
f620: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
f630: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
f640: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
f650: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
f660: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
f670: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
f680: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
f690: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
f6a0: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
f6b0: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
f6c0: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
f6d0: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
f6e0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
f6f0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
f700: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
f710: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
f720: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
f730: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
f740: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
f750: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
f760: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
f770: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f780: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
f790: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
f7a0: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
f7b0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
f7c0: 43 45 53 53 5f 52 45 41 44 0a 2a 2a 20 66 6c 61  CESS_READ.** fla
f7d0: 67 20 69 73 20 6e 65 76 65 72 20 61 63 74 75 61  g is never actua
f7e0: 6c 6c 79 20 75 73 65 64 20 61 6e 64 20 69 73 20  lly used and is 
f7f0: 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  not implemented 
f800: 69 6e 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  in the built-in.
f810: 2a 2a 20 56 46 53 65 73 20 6f 66 20 53 51 4c 69  ** VFSes of SQLi
f820: 74 65 2e 20 20 54 68 65 20 66 69 6c 65 20 69 73  te.  The file is
f830: 20 6e 61 6d 65 64 20 62 79 20 74 68 65 20 73 65   named by the se
f840: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 61 6e  cond argument an
f850: 64 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  d can be a.** di
f860: 72 65 63 74 6f 72 79 2e 20 54 68 65 20 78 41 63  rectory. The xAc
f870: 63 65 73 73 20 6d 65 74 68 6f 64 20 72 65 74 75  cess method retu
f880: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
f890: 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 73 6f  on success or so
f8a0: 6d 65 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 65  me.** non-zero e
f8b0: 72 72 6f 72 20 63 6f 64 65 20 69 66 20 74 68 65  rror code if the
f8c0: 72 65 20 69 73 20 61 6e 20 49 2f 4f 20 65 72 72  re is an I/O err
f8d0: 6f 72 20 6f 72 20 69 66 20 74 68 65 20 6e 61 6d  or or if the nam
f8e0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 69 6c 65  e of.** the file
f8f0: 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 73 65   given in the se
f900: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
f910: 20 69 6c 6c 65 67 61 6c 2e 20 20 49 66 20 53 51   illegal.  If SQ
f920: 4c 49 54 45 5f 4f 4b 0a 2a 2a 20 69 73 20 72 65  LITE_OK.** is re
f930: 74 75 72 6e 65 64 2c 20 74 68 65 6e 20 6e 6f 6e  turned, then non
f940: 2d 7a 65 72 6f 20 6f 72 20 7a 65 72 6f 20 69 73  -zero or zero is
f950: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
f960: 52 65 73 4f 75 74 20 74 6f 20 69 6e 64 69 63 61  ResOut to indica
f970: 74 65 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72  te.** whether or
f980: 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 69 73   not the file is
f990: 20 61 63 63 65 73 73 69 62 6c 65 2e 20 20 0a 2a   accessible.  .*
f9a0: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
f9b0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
f9c0: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
f9d0: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
f9e0: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
f9f0: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
fa00: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
fa10: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
fa20: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
fa30: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
fa40: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
fa50: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
fa60: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
fa70: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
fa80: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
fa90: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
faa0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
fab0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
fac0: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
fad0: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
fae0: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
faf0: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
fb00: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
fb10: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
fb20: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
fb30: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
fb40: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
fb50: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
fb60: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
fb70: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
fb80: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
fb90: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
fba0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
fbb0: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
fbc0: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
fbd0: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
fbe0: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
fbf0: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
fc00: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
fc10: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
fc20: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
fc30: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
fc40: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
fc50: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
fc60: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
fc70: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
fc80: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
fc90: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
fca0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
fcb0: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
fcc0: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
fcd0: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
fce0: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
fcf0: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
fd00: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
fd10: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
fd20: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
fd30: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
fd40: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
fd50: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
fd60: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
fd70: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
fd80: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
fd90: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
fda0: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
fdb0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
fdc0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
fdd0: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
fde0: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
fdf0: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
fe00: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
fe10: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
fe20: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
fe30: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
fe40: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
fe50: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
fe60: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
fe70: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
fe80: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
fe90: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
fea0: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
feb0: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
fec0: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
fed0: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
fee0: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
fef0: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
ff00: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
ff10: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
ff20: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
ff30: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
ff40: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
ff50: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
ff60: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
ff70: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
ff80: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
ff90: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
ffa0: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
ffb0: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
ffc0: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
ffd0: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
ffe0: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
fff0: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
10000 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
10010 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
10020 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
10030 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
10040 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
10050 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
10060 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
10070 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
10080 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
10090 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
100a0 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
100b0 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
100c0 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
100d0 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
100e0 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
100f0 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
10100 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
10110 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
10120 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
10130 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
10140 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
10150 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
10160 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
10170 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
10180 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
10190 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
101a0 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
101b0 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
101c0 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
101d0 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
101e0 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
101f0 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
10200 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
10210 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
10220 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
10230 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
10240 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
10250 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
10260 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
10270 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
10280 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
10290 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
102a0 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
102b0 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
102c0 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
102d0 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
102e0 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
102f0 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
10300 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
10310 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
10320 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
10330 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
10340 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
10350 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
10360 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
10370 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
10380 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
10390 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
103a0 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
103b0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
103c0 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
103d0 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
103e0 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
103f0 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
10400 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
10410 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
10420 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
10430 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
10440 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
10450 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
10460 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
10470 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
10480 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
10490 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
104a0 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
104b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
104c0 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
104d0 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
104e0 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
104f0 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
10500 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
10510 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
10520 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
10530 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
10540 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
10550 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
10560 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
10570 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
10580 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
10590 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
105a0 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
105b0 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
105c0 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
105d0 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
105e0 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
105f0 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
10600 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
10610 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
10620 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
10630 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
10640 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
10650 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
10660 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
10670 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
10680 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
10690 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
106a0 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
106b0 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
106c0 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
106d0 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
106e0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
106f0 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
10700 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
10710 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
10720 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
10730 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
10740 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
10750 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
10760 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
10770 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
10780 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
10790 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
107a0 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
107b0 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
107c0 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
107d0 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
107e0 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
107f0 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
10800 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
10810 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
10820 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
10830 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
10840 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
10850 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
10860 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
10870 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
10880 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
10890 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
108a0 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
108b0 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
108c0 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
108d0 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
108e0 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
108f0 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
10900 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
10910 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
10920 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
10930 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
10940 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
10950 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
10960 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
10970 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
10980 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
10990 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
109a0 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
109b0 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
109c0 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
109d0 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
109e0 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
109f0 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
10a00 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
10a10 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
10a20 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
10a30 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
10a40 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
10a50 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
10a60 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
10a70 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
10a80 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
10a90 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
10aa0 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
10ab0 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
10ac0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
10ad0 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
10ae0 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
10af0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
10b00 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
10b10 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
10b20 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
10b30 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
10b40 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
10b50 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
10b60 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
10b70 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
10b80 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
10b90 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
10ba0 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
10bb0 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
10bc0 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
10bd0 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
10be0 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
10bf0 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
10c00 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
10c10 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
10c20 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
10c30 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
10c40 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
10c50 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
10c60 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
10c70 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
10c80 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
10c90 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
10ca0 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
10cb0 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
10cc0 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
10cd0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
10ce0 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
10cf0 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
10d00 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
10d10 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
10d20 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
10d30 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
10d40 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
10d50 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
10d60 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
10d70 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
10d80 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
10d90 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
10da0 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
10db0 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
10dc0 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
10dd0 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
10de0 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
10df0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
10e00 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
10e10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
10e20 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
10e30 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
10e40 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
10e50 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
10e60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
10e70 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
10e80 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
10e90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10ea0 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
10eb0 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
10ec0 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
10ed0 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
10ee0 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
10ef0 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
10f00 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
10f10 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
10f20 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
10f30 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
10f40 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
10f50 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
10f60 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
10f70 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
10f80 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
10f90 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
10fa0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
10fb0 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
10fc0 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
10fd0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
10fe0 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
10ff0 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
11000 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
11010 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
11020 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
11030 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
11040 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
11050 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
11060 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
11070 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
11080 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
11090 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
110a0 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
110b0 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
110c0 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70  n on the corresp
110d0 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
110e0 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
110f0 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
11100 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
11110 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
11120 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
11130 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
11140 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
11150 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
11160 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
11170 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
11180 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
11190 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
111a0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
111b0 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
111c0 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
111d0 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
111e0 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
111f0 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
11200 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
11210 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
11220 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
11230 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
11240 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
11250 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
11260 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
11270 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
11280 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
11290 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
112a0 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
112b0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
112c0 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
112d0 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
112e0 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
112f0 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
11300 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
11310 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
11320 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
11330 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
11340 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
11350 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
11360 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
11370 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11380 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
11390 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
113a0 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
113b0 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
113c0 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
113d0 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
113e0 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
113f0 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
11400 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
11410 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
11420 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
11430 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
11440 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
11450 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
11460 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
11470 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
11480 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
11490 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
114a0 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
114b0 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
114c0 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
114d0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
114e0 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
114f0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11500 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
11510 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
11520 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
11530 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
11540 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
11550 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
11560 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
11570 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
11580 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
11590 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
115a0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
115b0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
115c0 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
115d0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
115e0 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
115f0 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
11600 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
11610 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
11620 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
11630 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
11640 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
11650 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
11660 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
11670 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
11680 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
11690 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
116a0 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
116b0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
116c0 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
116d0 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
116e0 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
116f0 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
11700 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
11710 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
11720 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
11730 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
11740 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
11750 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
11760 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
11770 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
11780 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
11790 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
117a0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
117b0 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
117c0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
117d0 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
117e0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
117f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
11800 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
11810 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
11820 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
11830 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
11840 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
11850 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
11860 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
11870 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
11880 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
11890 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
118a0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
118b0 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
118c0 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
118d0 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
118e0 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
118f0 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
11900 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
11910 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
11920 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
11930 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
11940 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
11950 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
11960 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
11970 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
11980 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
11990 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
119a0 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
119b0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
119c0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
119d0 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
119e0 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
119f0 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
11a00 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
11a10 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
11a20 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
11a30 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
11a40 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
11a50 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
11a60 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
11a70 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11a80 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
11a90 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
11aa0 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
11ab0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
11ac0 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
11ad0 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
11ae0 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
11af0 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
11b00 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11b10 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
11b20 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
11b30 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
11b40 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
11b50 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
11b60 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
11b70 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
11b80 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
11b90 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
11ba0 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
11bb0 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
11bc0 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
11bd0 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
11be0 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
11bf0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11c00 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
11c10 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
11c20 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
11c30 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
11c40 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
11c50 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
11c60 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
11c70 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
11c80 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
11c90 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
11ca0 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
11cb0 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
11cc0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
11cd0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
11ce0 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
11cf0 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
11d00 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
11d10 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
11d20 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
11d30 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11d40 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
11d50 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
11d60 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
11d70 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
11d80 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
11d90 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
11da0 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
11db0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
11dc0 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
11dd0 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
11de0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11df0 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
11e00 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
11e10 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
11e20 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
11e30 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
11e40 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
11e50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
11e60 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
11e70 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
11e80 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
11e90 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
11ea0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
11eb0 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
11ec0 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
11ed0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
11ee0 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
11ef0 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
11f00 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
11f10 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
11f20 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
11f30 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
11f40 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
11f50 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
11f60 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
11f70 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
11f80 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
11f90 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
11fa0 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
11fb0 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
11fc0 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
11fd0 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
11fe0 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
11ff0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12000 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
12010 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
12020 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
12030 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
12040 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
12050 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
12060 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
12070 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
12080 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
12090 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
120a0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
120b0 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
120c0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
120d0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
120e0 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
120f0 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
12100 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12110 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
12120 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
12130 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
12140 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
12150 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
12160 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
12170 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
12180 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
12190 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
121a0 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
121b0 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
121c0 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
121d0 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
121e0 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
121f0 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
12200 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
12210 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
12220 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
12230 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
12240 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
12250 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
12260 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
12270 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
12280 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
12290 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
122a0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
122b0 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
122c0 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
122d0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
122e0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
122f0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
12300 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
12310 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
12320 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
12330 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
12340 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
12350 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ilure..*/.int sq
12360 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
12370 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
12380 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
12390 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
123a0 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69  os_init(void);.i
123b0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nt sqlite3_os_en
123c0 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
123d0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
123e0 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
123f0 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
12400 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
12410 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
12420 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
12430 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
12440 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
12450 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
12460 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
12470 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
12480 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
12490 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
124a0 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
124b0 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
124c0 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
124d0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
124e0 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
124f0 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
12500 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
12510 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
12520 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
12530 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
12540 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
12550 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73  ..**.** <b>The s
12560 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
12570 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
12580 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68 65   threadsafe. The
12590 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
125a0 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74  must ensure that
125b0 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
125c0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
125d0 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
125e0 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
125f0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
12600 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f  () is running.</
12610 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  b>.**.** The sql
12620 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
12630 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f  terface.** may o
12640 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70  nly be invoked p
12650 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20  rior to library 
12660 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75  initialization u
12670 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
12680 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f  _initialize()] o
12690 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e  r after shutdown
126a0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75   by [sqlite3_shu
126b0 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66  tdown()]..** ^If
126c0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
126d0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65  ) is called afte
126e0 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  r [sqlite3_initi
126f0 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66  alize()] and bef
12700 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
12710 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e  shutdown()] then
12720 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20   it will return 
12730 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a  SQLITE_MISUSE..*
12740 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c  * Note, however,
12750 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63   that ^sqlite3_c
12760 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63  onfig() can be c
12770 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66  alled as part of
12780 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
12790 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70  tation of an app
127a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
127b0 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69   [sqlite3_os_ini
127c0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  t()]..**.** The 
127d0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
127e0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
127f0 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  () is an integer
12800 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  .** [configurati
12810 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
12820 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
12830 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
12840 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
12850 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
12860 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
12870 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
12880 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69  ng on the [confi
12890 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
128a0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
128b0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
128c0 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75   ^When a configu
128d0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
128e0 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
128f0 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
12900 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e  SQLITE_OK]..** ^
12910 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73  If the option is
12920 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69   unknown or SQLi
12930 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
12940 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a  set the option.*
12950 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
12960 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
12970 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
12980 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  de]..*/.int sqli
12990 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20  te3_config(int, 
129a0 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
129b0 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65  I3REF: Configure
129c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
129d0 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
129e0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
129f0 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
12a00 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
12a10 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
12a20 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
12a30 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
12a40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12a50 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
12a60 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
12a70 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
12a80 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
12a90 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
12aa0 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
12ab0 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
12ac0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
12ad0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
12ae0 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a  rst argument)..*
12af0 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
12b00 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
12b10 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c  te3_db_config(D,
12b20 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a  V,...)  is the.*
12b30 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  * [SQLITE_DBCONF
12b40 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63  IG_LOOKASIDE | c
12b50 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
12b60 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20  b] - an integer 
12b70 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e  code .** that in
12b80 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70  dicates what asp
12b90 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ect of the [data
12ba0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12bb0 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67   is being config
12bc0 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75  ured..** Subsequ
12bd0 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61  ent arguments va
12be0 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
12bf0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
12c00 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43  n verb..**.** ^C
12c10 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
12c20 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  db_config() retu
12c30 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
12c40 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74  and only if.** t
12c50 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69  he call is consi
12c60 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c  dered successful
12c70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
12c80 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74  _db_config(sqlit
12c90 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e  e3*, int op, ...
12ca0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
12cb0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
12cc0 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
12cd0 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
12ce0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
12cf0 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
12d00 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
12d10 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
12d20 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
12d30 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
12d40 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
12d50 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
12d60 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
12d70 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
12d80 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
12d90 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
12da0 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
12db0 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
12dc0 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
12dd0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
12de0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
12df0 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
12e00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
12e10 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LLOC] or [SQLITE
12e20 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
12e30 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61  C].  .** By crea
12e40 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65  ting an instance
12e50 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a   of this object.
12e60 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69  ** and passing i
12e70 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
12e80 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
12e90 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a  NFIG_MALLOC]).**
12ea0 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
12eb0 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63  ation, an applic
12ec0 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66  ation can specif
12ed0 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
12ee0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
12ef0 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
12f00 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
12f10 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
12f20 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  .** dynamic memo
12f30 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
12f40 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
12f50 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65   comes with seve
12f60 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65  ral [built-in me
12f70 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d  mory allocators]
12f80 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72  .** that are per
12f90 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20  fectly adequate 
12fa0 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c  for the overwhel
12fb0 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66  ming majority of
12fc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
12fd0 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f   and that this o
12fe0 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73  bject is only us
12ff0 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d  eful to a tiny m
13000 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  inority of appli
13010 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20  cations.** with 
13020 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f  specialized memo
13030 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
13040 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69  quirements.  Thi
13050 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61  s object is.** a
13060 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20  lso used during 
13070 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74  testing of SQLit
13080 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70  e in order to sp
13090 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
130a0 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
130b0 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69  llocator that si
130c0 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f  mulates memory o
130d0 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e  ut-of-memory con
130e0 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72  ditions in.** or
130f0 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68  der to verify th
13100 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65  at SQLite recove
13110 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72  rs gracefully fr
13120 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69  om such.** condi
13130 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
13140 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c   xMalloc, xReall
13150 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65  oc, and xFree me
13160 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
13170 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
13180 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20  oc(), realloc() 
13190 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74  and free() funct
131a0 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74  ions from the st
131b0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
131c0 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ..** ^SQLite gua
131d0 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
131e0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
131f0 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20   to.** xRealloc 
13200 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75  is always a valu
13210 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20  e returned by a 
13220 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52  prior call to xR
13230 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53  oundup..**.** xS
13240 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ize should retur
13250 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  n the allocated 
13260 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79  size of a memory
13270 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70   allocation.** p
13280 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
13290 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20  ed from xMalloc 
132a0 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68  or xRealloc.  Th
132b0 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
132c0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74  .** is always at
132d0 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73   least as big as
132e0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73   the requested s
132f0 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c  ize but may be l
13300 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  arger..**.** The
13310 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64   xRoundup method
13320 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f   returns what wo
13330 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63  uld be the alloc
13340 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20  ated size of.** 
13350 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
13360 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74  ion given a part
13370 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64  icular requested
13380 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d   size.  Most mem
13390 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
133a0 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72  s round up memor
133b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74  y allocations at
133c0 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65   least to the ne
133d0 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f  xt multiple.** o
133e0 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63  f 8.  Some alloc
133f0 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74  ators round up t
13400 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69  o a larger multi
13410 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65  ple or to a powe
13420 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79  r of 2..** Every
13430 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13440 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e  on request comin
13450 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71  g in through [sq
13460 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a  lite3_malloc()].
13470 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  ** or [sqlite3_r
13480 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20  ealloc()] first 
13490 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20  calls xRoundup. 
134a0 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74   If xRoundup ret
134b0 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74  urns 0, .** that
134c0 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72   causes the corr
134d0 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79  esponding memory
134e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66   allocation to f
134f0 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ail..**.** The x
13500 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74  Init method init
13510 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f  ializes the memo
13520 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46  ry allocator.  F
13530 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
13540 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65  t might allocate
13550 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74   any require mut
13560 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69  exes or initiali
13570 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ze internal data
13580 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20  .** structures. 
13590 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d   The xShutdown m
135a0 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
135b0 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79   (indirectly) by
135c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
135d0 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f  tdown()] and sho
135e0 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61  uld deallocate a
135f0 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71  ny resources acq
13600 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69  uired.** by xIni
13610 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61  t.  The pAppData
13620 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64   pointer is used
13630 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
13640 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e  ameter to.** xIn
13650 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  it and xShutdown
13660 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68  ..**.** SQLite h
13670 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
13680 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
13690 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e  STER] mutex when
136a0 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74   it invokes.** t
136b0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c  he xInit method,
136c0 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65   so the xInit me
136d0 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65  thod need not be
136e0 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
136f0 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d  e.** xShutdown m
13700 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61  ethod is only ca
13710 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  lled from [sqlit
13720 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73  e3_shutdown()] s
13730 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  o it does.** not
13740 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65   need to be thre
13750 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20  adsafe either.  
13760 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65  For all other me
13770 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a  thods, SQLite.**
13780 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
13790 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
137a0 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f  MEM] mutex as lo
137b0 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51  ng as the.** [SQ
137c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
137d0 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61  TATUS] configura
137e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74  tion option is t
137f0 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a  urned on (which.
13800 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61  ** it is by defa
13810 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20  ult) and so the 
13820 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f  methods are auto
13830 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c  matically serial
13840 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  ized..** However
13850 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  , if [SQLITE_CON
13860 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69  FIG_MEMSTATUS] i
13870 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e  s disabled, then
13880 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   the other.** me
13890 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68  thods must be th
138a0 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65  readsafe or else
138b0 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20   make their own 
138c0 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72  arrangements for
138d0 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f  .** serializatio
138e0 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
138f0 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
13900 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74  e xInit() more t
13910 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74  han once without
13920 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a   an intervening.
13930 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74  ** call to xShut
13940 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  down()..*/.typed
13950 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
13960 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71  3_mem_methods sq
13970 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
13980 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
13990 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a  3_mem_methods {.
139a0 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f    void *(*xMallo
139b0 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  c)(int);        
139c0 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63   /* Memory alloc
139d0 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a  ation function *
139e0 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65  /.  void (*xFree
139f0 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
13a00 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69     /* Free a pri
13a10 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  or allocation */
13a20 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c  .  void *(*xReal
13a30 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b  loc)(void*,int);
13a40 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61    /* Resize an a
13a50 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
13a60 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64  nt (*xSize)(void
13a70 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
13a80 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
13a90 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   of an allocatio
13aa0 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f  n */.  int (*xRo
13ab0 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20  undup)(int);    
13ac0 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75        /* Round u
13ad0 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74  p request size t
13ae0 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  o allocation siz
13af0 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e  e */.  int (*xIn
13b00 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  it)(void*);     
13b10 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c        /* Initial
13b20 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
13b30 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
13b40 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28  id (*xShutdown)(
13b50 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20  void*);      /* 
13b60 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  Deinitialize the
13b70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
13b80 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  r */.  void *pAp
13b90 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
13ba0 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e        /* Argumen
13bb0 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64  t to xInit() and
13bc0 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a   xShutdown() */.
13bd0 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
13be0 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
13bf0 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  n Options.** KEY
13c00 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72  WORDS: {configur
13c10 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a  ation option}.**
13c20 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
13c30 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
13c40 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
13c50 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13c60 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
13c70 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
13c80 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
13c90 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
13ca0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
13cb0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
13cc0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13cd0 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
13ce0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
13cf0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
13d00 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
13d10 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13d20 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
13d30 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
13d40 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
13d50 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
13d60 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
13d70 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74  ite3_config()] t
13d80 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
13d90 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
13da0 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
13db0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
13dc0 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
13dd0 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
13de0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
13df0 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
13e00 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
13e10 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13e20 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
13e30 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
13e40 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13e50 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20  _SINGLETHREAD]] 
13e60 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13e70 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f  G_SINGLETHREAD</
13e80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
13e90 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
13ea0 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
13eb0 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
13ec0 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
13ed0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
13ee0 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20  Single-thread.  
13ef0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
13f00 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  it disables.** a
13f10 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
13f20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
13f30 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
13f40 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
13f50 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
13f60 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53   thread.   ^If S
13f70 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
13f80 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
13f90 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13fa0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
13fb0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
13fc0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
13fd0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
13fe0 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65  ssible to change
13ff0 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
14000 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64  mode] from its d
14010 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
14020 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  of Single-thread
14030 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33   and so [sqlite3
14040 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
14050 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49  return .** [SQLI
14060 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
14070 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
14080 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
14090 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69  ETHREAD.** confi
140a0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
140b0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
140c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
140d0 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ITHREAD]] <dt>SQ
140e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
140f0 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ITHREAD</dt>.** 
14100 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
14110 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
14120 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
14130 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
14140 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
14150 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74  mode] to Multi-t
14160 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
14170 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
14180 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
14190 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
141a0 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
141b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
141c0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
141d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
141e0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
141f0 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
14200 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
14210 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
14220 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
14230 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
14240 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
14250 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
14260 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
14270 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
14280 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
14290 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
142a0 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e  ent as long as n
142b0 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74  o two threads at
142c0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
142d0 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61   same.** [databa
142e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
142f0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
14300 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
14310 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
14320 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
14330 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
14340 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
14350 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
14360 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
14370 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
14380 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74   set the Multi-t
14390 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
143a0 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
143b0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
143c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
143d0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
143e0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
143f0 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
14400 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66  MULTITHREAD conf
14410 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14420 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
14430 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
14440 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51  IALIZED]] <dt>SQ
14450 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
14460 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
14470 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
14480 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
14490 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
144a0 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
144b0 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
144c0 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a  ode] to Serializ
144d0 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  ed. In other wor
144e0 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ds, this option 
144f0 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
14500 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
14510 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
14520 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
14530 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14540 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
14550 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
14560 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
14570 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
14580 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
14590 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
145a0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
145b0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
145c0 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
145d0 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
145e0 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
145f0 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
14600 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
14610 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
14620 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
14630 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
14640 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
14650 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
14660 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14670 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
14680 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
14690 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
146a0 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
146b0 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
146c0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
146d0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
146e0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
146f0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
14700 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
14710 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
14720 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
14730 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
14740 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65  et the Serialize
14750 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
14760 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
14770 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
14780 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
14790 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
147a0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
147b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
147c0 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61  ALIZED configura
147d0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
147e0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
147f0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d  _CONFIG_MALLOC]]
14800 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14810 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  IG_MALLOC</dt>.*
14820 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
14830 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
14840 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  C option takes a
14850 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
14860 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20   which is .** a 
14870 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
14880 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
14890 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
148a0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
148b0 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73  * The argument s
148c0 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
148d0 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
148e0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
148f0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
14900 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
14910 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
14920 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
14930 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
14940 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
14950 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
14960 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
14970 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
14980 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
14990 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
149a0 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
149b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
149c0 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
149d0 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
149e0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
149f0 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  _GETMALLOC]] <dt
14a00 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
14a10 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
14a20 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
14a30 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
14a40 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
14a50 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
14a60 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
14a70 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
14a80 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
14a90 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
14aa0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
14ab0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
14ac0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
14ad0 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
14ae0 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
14af0 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
14b00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14b10 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
14b20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
14b30 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
14b40 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
14b50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14b60 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
14b70 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61  th a wrapper tha
14b80 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65  t simulations me
14b90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14ba0 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72  failure or.** tr
14bb0 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67  acks memory usag
14bc0 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  e, for example. 
14bd0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14be0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c  LITE_CONFIG_SMAL
14bf0 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  L_MALLOC]] <dt>S
14c00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41  QLITE_CONFIG_SMA
14c10 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  LL_MALLOC</dt>.*
14c20 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
14c30 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f  TE_CONFIG_SMALL_
14c40 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61  MALLOC option ta
14c50 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  kes single argum
14c60 65 6e 74 20 6f 66 0a 2a 2a 20 74 79 70 65 20 69  ent of.** type i
14c70 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20  nt, interpreted 
14c80 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68  as a boolean, wh
14c90 69 63 68 20 69 66 20 74 72 75 65 20 70 72 6f 76  ich if true prov
14ca0 69 64 65 73 20 61 20 68 69 6e 74 20 74 6f 0a 2a  ides a hint to.*
14cb0 2a 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74  * SQLite that it
14cc0 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 20 6c 61   should avoid la
14cd0 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  rge memory alloc
14ce0 61 74 69 6f 6e 73 20 69 66 20 70 6f 73 73 69 62  ations if possib
14cf0 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  le..** SQLite wi
14d00 6c 6c 20 72 75 6e 20 66 61 73 74 65 72 20 69 66  ll run faster if
14d10 20 69 74 20 69 73 20 66 72 65 65 20 74 6f 20 6d   it is free to m
14d20 61 6b 65 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79  ake large memory
14d30 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 0a 2a 2a   allocations,.**
14d40 20 62 75 74 20 73 6f 6d 65 20 61 70 70 6c 69 63   but some applic
14d50 61 74 69 6f 6e 20 6d 69 67 68 74 20 70 72 65 66  ation might pref
14d60 65 72 20 74 6f 20 72 75 6e 20 73 6c 6f 77 65 72  er to run slower
14d70 20 69 6e 20 65 78 63 68 61 6e 67 65 20 66 6f 72   in exchange for
14d80 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 61  .** guarantees a
14d90 62 6f 75 74 20 6d 65 6d 6f 72 79 20 66 72 61 67  bout memory frag
14da0 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 61  mentation that a
14db0 72 65 20 70 6f 73 73 69 62 6c 65 20 69 66 20 6c  re possible if l
14dc0 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  arge.** allocati
14dd0 6f 6e 73 20 61 72 65 20 61 76 6f 69 64 65 64 2e  ons are avoided.
14de0 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e    This hint is n
14df0 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e 0a 2a 2a 20  ormally off..** 
14e00 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14e10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
14e20 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49  TATUS]] <dt>SQLI
14e30 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
14e40 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TUS</dt>.** <dd>
14e50 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
14e60 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70  FIG_MEMSTATUS op
14e70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
14e80 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
14e90 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72  pe int,.** inter
14ea0 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
14eb0 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
14ec0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
14ed0 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
14ee0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
14ef0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
14f00 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20  . ^(When memory 
14f10 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
14f20 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73  stics are.** dis
14f30 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f  abled, the follo
14f40 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
14f50 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
14f60 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
14f70 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
14f80 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
14f90 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
14fa0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
14fb0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
14fc0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
14fd0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
14fe0 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
14ff0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
15000 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f  tus64()].**   </
15010 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79  ul>)^.** ^Memory
15020 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
15030 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c  istics are enabl
15040 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e  ed by default un
15050 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a  less SQLite is.*
15060 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  * compiled with 
15070 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f  [SQLITE_DEFAULT_
15080 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20  MEMSTATUS]=0 in 
15090 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72  which case memor
150a0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  y.** allocation 
150b0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
150c0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
150d0 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  lt..** </dd>.**.
150e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
150f0 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74  IG_SCRATCH]] <dt
15100 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
15110 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  CRATCH</dt>.** <
15120 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43  dd> The SQLITE_C
15130 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70  ONFIG_SCRATCH op
15140 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  tion is no longe
15150 72 20 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 64 3e  r used..** </dd>
15160 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15170 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
15180 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
15190 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
151a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
151b0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
151c0 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20  AGECACHE option 
151d0 73 70 65 63 69 66 69 65 73 20 61 20 6d 65 6d 6f  specifies a memo
151e0 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20  ry pool.** that 
151f0 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
15200 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
15210 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20  page cache with 
15220 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65  the default page
15230 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
15240 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54  entation.  .** T
15250 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
15260 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f  n option is a no
15270 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c 69 63  -op if an applic
15280 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
15290 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
152a0 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
152b0 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53  ded using the [S
152c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
152d0 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65  CHE2]..** ^There
152e0 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
152f0 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43  ents to SQLITE_C
15300 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a  ONFIG_PAGECACHE:
15310 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   A pointer to.**
15320 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
15330 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74  memory (pMem), t
15340 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
15350 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20  page cache line 
15360 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
15370 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63 68 65   number of cache
15380 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54   lines (N)..** T
15390 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73  he sz argument s
153a0 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a  hould be the siz
153b0 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  e of the largest
153c0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a   database page.*
153d0 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77  * (a power of tw
153e0 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e  o between 512 an
153f0 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f  d 65536) plus so
15400 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20 66  me extra bytes f
15410 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20  or each.** page 
15420 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75  header.  ^The nu
15430 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62 79  mber of extra by
15440 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74 68  tes needed by th
15450 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a  e page header.**
15460 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
15470 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49 54 45  ed using [SQLITE
15480 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
15490 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73  DRSZ]..** ^It is
154a0 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74   harmless, apart
154b0 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64   from the wasted
154c0 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20   memory,.** for 
154d0 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72  the sz parameter
154e0 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74 68   to be larger th
154f0 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20 54  an necessary.  T
15500 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d  he pMem.** argum
15510 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69 74 68  ent must be eith
15520 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
15530 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  r or a pointer t
15540 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  o an 8-byte.** a
15550 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20  ligned block of 
15560 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61  memory of at lea
15570 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f  st sz*N bytes, o
15580 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75 62 73  therwise.** subs
15590 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
155a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
155b0 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e   ^When pMem is n
155c0 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20  ot NULL, SQLite 
155d0 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f 20 75  will strive to u
155e0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
155f0 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74  ovided.** to sat
15600 69 73 66 79 20 70 61 67 65 20 63 61 63 68 65 20  isfy page cache 
15610 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62  needs, falling b
15620 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ack to [sqlite3_
15630 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20  malloc()] if.** 
15640 61 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e  a page cache lin
15650 65 20 69 73 20 6c 61 72 67 65 72 20 74 68 61 6e  e is larger than
15660 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69 66 20   sz bytes or if 
15670 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d 20  all of the pMem 
15680 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65 78 68  buffer.** is exh
15690 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70  austed..** ^If p
156a0 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20  Mem is NULL and 
156b0 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  N is non-zero, t
156c0 68 65 6e 20 65 61 63 68 20 64 61 74 61 62 61 73  hen each databas
156d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
156e0 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61 6c 20  does an initial 
156f0 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  bulk allocation 
15700 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d  for page cache m
15710 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73  emory.** from [s
15720 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
15730 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f 72 20   sufficient for 
15740 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20 69 66  N cache lines if
15750 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 20 6f   N is positive o
15760 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20  r.** of -1024*N 
15770 62 79 74 65 73 20 69 66 20 4e 20 69 73 20 6e 65  bytes if N is ne
15780 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20 61 64  gative, . ^If ad
15790 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
157a0 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
157b0 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
157c0 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
157d0 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a  by the initial.*
157e0 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  * allocation, th
157f0 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  en SQLite goes t
15800 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
15810 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c 79 20  c()] separately 
15820 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64 64 69  for each.** addi
15830 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e  tional cache lin
15840 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
15850 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  [SQLITE_CONFIG_H
15860 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAP]] <dt>SQLITE
15870 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74  _CONFIG_HEAP</dt
15880 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
15890 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
158a0 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  P option specifi
158b0 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
158c0 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68  ry buffer .** th
158d0 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  at SQLite will u
158e0 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
158f0 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
15900 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
15910 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73  s.** beyond thos
15920 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62  e provided for b
15930 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
15940 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
15950 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
15960 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69  IG_HEAP option i
15970 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
15980 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
15990 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65  mpiled.** with e
159a0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
159b0 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
159c0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
159d0 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74  MEMSYS5] and ret
159e0 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
159f0 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65  ERROR] if invoke
15a00 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20  d otherwise..** 
15a10 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65  ^There are three
15a20 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51   arguments to SQ
15a30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
15a40 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61  :.** An 8-byte a
15a50 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
15a60 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
15a70 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
15a80 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
15a90 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
15aa0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
15ab0 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e  ation size..** ^
15ac0 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  If the first poi
15ad0 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
15ae0 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
15af0 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
15b00 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
15b10 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
15b20 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
15b30 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
15b40 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
15b50 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
15b60 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
15b70 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
15b80 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
15b90 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d    ^If the.** mem
15ba0 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ory pointer is n
15bb0 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  ot NULL then the
15bc0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
15bd0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
15be0 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
15bf0 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
15c00 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
15c10 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
15c20 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
15c30 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
15c40 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
15c50 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
15c60 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
15c70 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
15c80 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
15c90 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
15ca0 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69  ned..** The mini
15cb0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
15cc0 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74  ize is capped at
15cd0 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62   2**12. Reasonab
15ce0 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
15cf0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
15d00 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
15d10 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a   2**5 through 2*
15d20 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  *8.</dd>.**.** [
15d30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
15d40 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
15d50 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
15d60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
15d70 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15d80 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b  MUTEX option tak
15d90 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
15da0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a  ment which is a.
15db0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
15dc0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
15dd0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
15de0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
15df0 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  re..** The argum
15e00 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 6c  ent specifies al
15e10 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
15e20 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  vel mutex routin
15e30 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a  es to be used.**
15e40 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75   in place the mu
15e50 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69  tex routines bui
15e60 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
15e70 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
15e80 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
15e90 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
15ea0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
15eb0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
15ec0 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61  re before the ca
15ed0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
15ee0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75  3_config()] retu
15ef0 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  rns. ^If SQLite 
15f00 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
15f10 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
15f20 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
15f30 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
15f40 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
15f50 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
15f60 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
15f70 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
15f80 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
15f90 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
15fa0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
15fb0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
15fc0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
15fd0 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66  ONFIG_MUTEX conf
15fe0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
15ff0 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
16000 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
16010 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
16020 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
16030 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
16040 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
16050 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
16060 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16070 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f  G_GETMUTEX optio
16080 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
16090 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a   argument which.
160a0 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
160b0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
160c0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
160d0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
160e0 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a  ructure.  The.**
160f0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
16100 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
16110 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
16120 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
16130 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78  ly defined mutex
16140 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
16150 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
16160 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
16170 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
16180 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e  mutex allocation
16190 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
161a0 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64  h a wrapper used
161b0 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20   to track mutex 
161c0 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72  usage for perfor
161d0 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69  mance.** profili
161e0 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66  ng or testing, f
161f0 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49  or example.   ^I
16200 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
16210 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
16220 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
16230 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
16240 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
16250 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
16260 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
16270 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
16280 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
16290 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
162a0 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
162b0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
162c0 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
162d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
162e0 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  ETMUTEX configur
162f0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
16300 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
16310 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
16320 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
16330 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
16340 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
16350 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
16360 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
16370 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16380 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e  LOOKASIDE option
16390 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
163a0 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
163b0 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75  ine.** the defau
163c0 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61  lt size of looka
163d0 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65  side memory on e
163e0 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ach [database co
163f0 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  nnection]..** Th
16400 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
16410 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
16420 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
16430 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e  e buffer slot an
16440 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20  d the second is 
16450 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
16460 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64   slots allocated
16470 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
16480 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20  e connection.)^ 
16490 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   ^(SQLITE_CONFIG
164a0 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65  _LOOKASIDE.** se
164b0 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c  ts the <i>defaul
164c0 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
164d0 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
164e0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
164f0 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20  SIDE].** option 
16500 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
16510 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
16520 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
16530 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
16540 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
16550 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
16560 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
16570 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
16580 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d  CONFIG_PCACHE2]]
16590 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
165a0 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  IG_PCACHE2</dt>.
165b0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
165c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
165d0 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  HE2 option takes
165e0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
165f0 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20  nt which is .** 
16600 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
16610 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
16620 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
16630 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73  .  This object s
16640 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
16650 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 63  interface to a c
16660 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65  ustom page cache
16670 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
16680 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61  )^.** ^SQLite ma
16690 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
166a0 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  e [sqlite3_pcach
166b0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
166c0 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ct.</dd>.**.** [
166d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
166e0 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  ETPCACHE2]] <dt>
166f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16700 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  TPCACHE2</dt>.**
16710 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
16720 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
16730 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
16740 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
16750 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
16760 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
16770 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
16780 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
16790 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
167a0 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65   of.** the curre
167b0 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  nt page cache im
167c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
167d0 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e  o that object.)^
167e0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
167f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
16800 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
16810 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a  NFIG_LOG</dt>.**
16820 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45   <dd> The SQLITE
16830 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
16840 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  on is used to co
16850 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69  nfigure the SQLi
16860 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72  te.** global [er
16870 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54  ror log]..** (^T
16880 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
16890 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _LOG option take
168a0 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a  s two arguments:
168b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
168c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ** function with
168d0 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72   a call signatur
168e0 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69  e of void(*)(voi
168f0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
16900 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70  r*), .** and a p
16910 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20  ointer to void. 
16920 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
16930 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
16940 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69  NULL, it is.** i
16950 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74  nvoked by [sqlit
16960 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f  e3_log()] to pro
16970 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e  cess each loggin
16980 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
16990 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f  e.** function po
169a0 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74  inter is NULL, t
169b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  he [sqlite3_log(
169c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63  )] interface bec
169d0 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a  omes a no-op..**
169e0 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74   ^The void point
169f0 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73  er that is the s
16a00 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
16a10 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
16a20 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64  LOG is.** passed
16a30 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
16a40 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
16a50 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
16a60 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
16a70 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68  r.** function wh
16a80 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63  enever that func
16a90 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
16aa0 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61    ^The second pa
16ab0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
16ac0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
16ad0 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  n is a copy of t
16ae0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
16af0 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  er to the corres
16b00 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  ponding.** [sqli
16b10 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20  te3_log()] call 
16b20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20  and is intended 
16b30 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20  to be a [result 
16b40 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
16b50 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
16b60 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69  code].  ^The thi
16b70 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  rd parameter pas
16b80 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65  sed to the logge
16b90 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73  r is.** log mess
16ba0 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74  age after format
16bb0 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65  ting via [sqlite
16bc0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a  3_snprintf()]..*
16bd0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67  * The SQLite log
16be0 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69  ging interface i
16bf0 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b  s not reentrant;
16c00 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
16c10 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
16c20 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
16c30 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76  ion must not inv
16c40 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  oke any SQLite i
16c50 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20  nterface..** In 
16c60 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
16c70 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
16c80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
16c90 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
16ca0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
16cb0 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64   threadsafe. </d
16cc0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
16cd0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c  E_CONFIG_URI]] <
16ce0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16cf0 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68  _URI.** <dd>^(Th
16d00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16d10 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  URI option takes
16d20 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
16d30 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a  nt of type int..
16d40 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  ** If non-zero, 
16d50 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
16d60 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
16d70 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61  abled. If the pa
16d80 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c  rameter is zero,
16d90 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e  .** then URI han
16da0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
16db0 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49  y disabled.)^ ^I
16dc0 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  f URI handling i
16dd0 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e  s globally.** en
16de0 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e  abled, all filen
16df0 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b  ames passed to [
16e00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
16e10 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
16e20 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
16e30 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a  3_open16()] or.*
16e40 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  * specified as p
16e50 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20  art of [ATTACH] 
16e60 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74  commands are int
16e70 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
16e80 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  , regardless.** 
16e90 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
16ea0 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  t the [SQLITE_OP
16eb0 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20  EN_URI] flag is 
16ec0 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74  set when the dat
16ed0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
16ee0 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
16ef0 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c  If it is globall
16f00 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65  y disabled, file
16f10 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c  names are.** onl
16f20 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  y interpreted as
16f30 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c   URIs if the SQL
16f40 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61  ITE_OPEN_URI fla
16f50 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
16f60 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
16f70 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
16f80 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74  ed. ^(By default
16f90 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  , URI handling i
16fa0 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69  s globally.** di
16fb0 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61  sabled. The defa
16fc0 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65  ult value may be
16fd0 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70   changed by comp
16fe0 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a  iling with the.*
16ff0 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  * [SQLITE_USE_UR
17000 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  I] symbol define
17010 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d.)^.**.** [[SQL
17020 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
17030 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d  ING_INDEX_SCAN]]
17040 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
17050 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
17060 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54  X_SCAN.** <dd>^T
17070 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
17080 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
17090 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65  SCAN option take
170a0 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67  s a single integ
170b0 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77  er.** argument w
170c0 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65  hich is interpre
170d0 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
170e0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61   in order to ena
170f0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a  ble or disable.*
17100 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  * the use of cov
17110 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
17120 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
17130 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  ns in the query 
17140 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54  optimizer..** ^T
17150 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
17160 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64  ng is determined
17170 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49  .** by the [SQLI
17180 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e  TE_ALLOW_COVERIN
17190 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f  G_INDEX_SCAN] co
171a0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
171b0 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a  n, or is "on".**
171c0 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65   if that compile
171d0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
171e0 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20  omitted..** The 
171f0 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62  ability to disab
17200 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  le the use of co
17210 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
17220 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
17230 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73  ans.** is becaus
17240 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74  e some incorrect
17250 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20  ly coded legacy 
17260 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67  applications mig
17270 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a  ht malfunction.*
17280 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d  * when the optim
17290 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  ization is enabl
172a0 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74  ed.  Providing t
172b0 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a  he ability to.**
172c0 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74   disable the opt
172d0 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73  imization allows
172e0 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67   the older, bugg
172f0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  y application co
17300 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  de to work.** wi
17310 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65  thout change eve
17320 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72  n with newer ver
17330 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
17340 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
17350 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20  CONFIG_PCACHE]] 
17360 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
17370 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c  GETPCACHE]].** <
17380 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17390 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49  _PCACHE and SQLI
173a0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
173b0 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73  CHE.** <dd> Thes
173c0 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62  e options are ob
173d0 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c  solete and shoul
173e0 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79  d not be used by
173f0 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68   new code..** Th
17400 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20  ey are retained 
17410 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
17420 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20  mpatibility but 
17430 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a  are now no-ops..
17440 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
17450 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
17460 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  QLLOG]].** <dt>S
17470 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
17480 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  LOG.** <dd>This 
17490 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
174a0 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69  vailable if sqli
174b0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
174c0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
174d0 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47  TE_ENABLE_SQLLOG
174e0 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
174f0 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54  macro defined. T
17500 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
17510 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61  t should.** be a
17520 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75   pointer to a fu
17530 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76  nction of type v
17540 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
17550 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72  ite3*,const char
17560 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20  *, int)..** The 
17570 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65  second should be
17580 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29   of type (void*)
17590 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  . The callback i
175a0 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65  s invoked by the
175b0 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74   library.** in t
175c0 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69  hree separate ci
175d0 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65  rcumstances, ide
175e0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76  ntified by the v
175f0 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
17600 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
17610 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66  ameter. If the f
17620 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
17630 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64  is 0, then the d
17640 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17650 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  on.** passed as 
17660 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
17670 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65  ent has just bee
17680 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68  n opened. The th
17690 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
176a0 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66  points to a buff
176b0 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  er containing th
176c0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61  e name of the ma
176d0 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
176e0 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72  . If the.** four
176f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
17700 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
17710 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74  statement that t
17720 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
17730 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  er.** points to 
17740 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78  has just been ex
17750 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74  ecuted. Or, if t
17760 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
17770 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a  ter is 2, then.*
17780 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  * the connection
17790 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73   being passed as
177a0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
177b0 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63  meter is being c
177c0 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68  losed. The.** th
177d0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
177e0 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20   passed NULL In 
177f0 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65  this case.  An e
17800 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20  xample of using 
17810 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  this.** configur
17820 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e  ation option can
17830 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20   be seen in the 
17840 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20  "test_sqllog.c" 
17850 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a  source file in.*
17860 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20  * the canonical 
17870 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72  SQLite source tr
17880 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ee.</dd>.**.** [
17890 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
178a0 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  MAP_SIZE]].** <d
178b0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
178c0 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64  MMAP_SIZE.** <dd
178d0 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  >^SQLITE_CONFIG_
178e0 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20  MMAP_SIZE takes 
178f0 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67  two 64-bit integ
17900 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36  er (sqlite3_int6
17910 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  4) values.** tha
17920 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c  t are the defaul
17930 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69  t mmap size limi
17940 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73  t (the default s
17950 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50  etting for.** [P
17960 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
17970 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  ) and the maximu
17980 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
17990 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54  ize limit..** ^T
179a0 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
179b0 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  ng can be overri
179c0 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74  dden by each dat
179d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
179e0 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72   using.** either
179f0 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61   the [PRAGMA mma
17a00 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c  p_size] command,
17a10 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65   or by using the
17a20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
17a30 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
17a40 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68  e control.  ^(Th
17a50 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
17a60 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77  d mmap size.** w
17a70 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20  ill be silently 
17a80 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63  truncated if nec
17a90 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 69  essary so that i
17aa0 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65  t does not excee
17ab0 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d the.** compile
17ac0 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d  -time maximum mm
17ad0 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74  ap size set by t
17ae0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41  he.** [SQLITE_MA
17af0 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d  X_MMAP_SIZE] com
17b00 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
17b10 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65  .)^.** ^If eithe
17b20 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  r argument to th
17b30 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67  is option is neg
17b40 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74  ative, then that
17b50 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
17b60 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63  changed to its c
17b70 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61  ompile-time defa
17b80 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ult..**.** [[SQL
17b90 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
17ba0 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  _HEAPSIZE]].** <
17bb0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17bc0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a  _WIN32_HEAPSIZE.
17bd0 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
17be0 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
17bf0 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20  HEAPSIZE option 
17c00 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
17c10 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a  e if SQLite is.*
17c20 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57  * compiled for W
17c30 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 20  indows with the 
17c40 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41  [SQLITE_WIN32_MA
17c50 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73  LLOC] pre-proces
17c60 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66  sor macro.** def
17c70 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f  ined. ^SQLITE_CO
17c80 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
17c90 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62  IZE takes a 32-b
17ca0 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
17cb0 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61  ger value.** tha
17cc0 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
17cd0 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
17ce0 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70  the created heap
17cf0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
17d00 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
17d10 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  DRSZ]].** <dt>SQ
17d20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
17d30 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e  HE_HDRSZ.** <dd>
17d40 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
17d50 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20  IG_PCACHE_HDRSZ 
17d60 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
17d70 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20  ingle parameter 
17d80 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
17d90 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
17da0 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20 69  ger and writes i
17db0 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72  nto that integer
17dc0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
17dd0 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65  xtra.** bytes pe
17de0 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64 20  r page required 
17df0 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69 6e  for each page in
17e00 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
17e10 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
17e20 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74  he amount of ext
17e30 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72 65  ra space require
17e40 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70  d can change dep
17e50 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
17e60 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65  mpiler,.** targe
17e70 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20  t platform, and 
17e80 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a  SQLite version..
17e90 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
17ea0 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a  ONFIG_PMASZ]].**
17eb0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
17ec0 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e  IG_PMASZ.** <dd>
17ed0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
17ee0 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20  IG_PMASZ option 
17ef0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
17f00 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
17f10 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64  * is an unsigned
17f20 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74   integer and set
17f30 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50  s the "Minimum P
17f40 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65  MA Size" for the
17f50 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a   multithreaded.*
17f60 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74  * sorter to that
17f70 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64   integer.  The d
17f80 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50  efault minimum P
17f90 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20 62  MA Size is set b
17fa0 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
17fb0 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63  _SORTER_PMASZ] c
17fc0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
17fd0 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73  on.  New threads
17fe0 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a   are launched.**
17ff0 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f   to help with so
18000 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68  rt operations wh
18010 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64  en multithreaded
18020 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65   sorting.** is e
18030 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68  nabled (using th
18040 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64  e [PRAGMA thread
18050 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20  s] command) and 
18060 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f  the amount of co
18070 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73  ntent.** to be s
18080 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74 68  orted exceeds th
18090 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65  e page size time
180a0 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66  s the minimum of
180b0 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20   the.** [PRAGMA 
180c0 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74  cache_size] sett
180d0 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c  ing and this val
180e0 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ue..**.** [[SQLI
180f0 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
18100 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64  NL_SPILL]].** <d
18110 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
18120 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a  STMTJRNL_SPILL.*
18130 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
18140 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
18150 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e 20 74  L_SPILL option t
18160 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61  akes a single pa
18170 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a  rameter which.**
18180 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b 73 74   becomes the [st
18190 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d  atement journal]
181a0 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74   spill-to-disk t
181b0 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b  hreshold.  .** [
181c0 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61  Statement journa
181d0 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69 6e 20  ls] are held in 
181e0 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74 68 65  memory until the
181f0 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79 74 65  ir size (in byte
18200 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20 74 68  s).** exceeds th
18210 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20 61 74  is threshold, at
18220 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74 68 65   which point the
18230 79 20 61 72 65 20 77 72 69 74 74 65 6e 20 74 6f  y are written to
18240 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20   disk..** Or if 
18250 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20 69 73  the threshold is
18260 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74 20 6a   -1, statement j
18270 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c 77 61  ournals are alwa
18280 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63 6c 75  ys held.** exclu
18290 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f 72 79  sively in memory
182a0 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e 79 20  ..** Since many 
182b0 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61  statement journa
182c0 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d 65 20  ls never become 
182d0 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67 20 74  large, setting t
182e0 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68 72 65  he spill.** thre
182f0 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c 75 65  shold to a value
18300 20 73 75 63 68 20 61 73 20 36 34 4b 69 42 20 63   such as 64KiB c
18310 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64 75 63  an greatly reduc
18320 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 0a  e the amount of.
18330 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65 64 20  ** I/O required 
18340 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61 74 65  to support state
18350 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  ment rollback..*
18360 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  * The default va
18370 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73 65 74  lue for this set
18380 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f 6c 6c  ting is controll
18390 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  ed by the.** [SQ
183a0 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  LITE_STMTJRNL_SP
183b0 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ILL] compile-tim
183c0 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  e option..**.** 
183d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
183e0 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 5d 5d  SORTERREF_SIZE]]
183f0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
18400 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f  ONFIG_SORTERREF_
18410 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  SIZE.** <dd>The 
18420 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4f  SQLITE_CONFIG_SO
18430 52 54 45 52 52 45 46 5f 53 49 5a 45 20 6f 70 74  RTERREF_SIZE opt
18440 69 6f 6e 20 61 63 63 65 70 74 73 20 61 20 73 69  ion accepts a si
18450 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 0a 2a  ngle parameter.*
18460 2a 20 6f 66 20 74 79 70 65 20 28 69 6e 74 29 20  * of type (int) 
18470 2d 20 74 68 65 20 6e 65 77 20 76 61 6c 75 65 20  - the new value 
18480 6f 66 20 74 68 65 20 73 6f 72 74 65 72 2d 72 65  of the sorter-re
18490 66 65 72 65 6e 63 65 20 73 69 7a 65 20 74 68 72  ference size thr
184a0 65 73 68 6f 6c 64 2e 0a 2a 2a 20 55 73 75 61 6c  eshold..** Usual
184b0 6c 79 2c 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ly, when SQLite 
184c0 75 73 65 73 20 61 6e 20 65 78 74 65 72 6e 61 6c  uses an external
184d0 20 73 6f 72 74 20 74 6f 20 6f 72 64 65 72 20 72   sort to order r
184e0 65 63 6f 72 64 73 20 61 63 63 6f 72 64 69 6e 67  ecords according
184f0 0a 2a 2a 20 74 6f 20 61 6e 20 4f 52 44 45 52 20  .** to an ORDER 
18500 42 59 20 63 6c 61 75 73 65 2c 20 61 6c 6c 20 66  BY clause, all f
18510 69 65 6c 64 73 20 72 65 71 75 69 72 65 64 20 62  ields required b
18520 79 20 74 68 65 20 63 61 6c 6c 65 72 20 61 72 65  y the caller are
18530 20 70 72 65 73 65 6e 74 20 69 6e 20 74 68 65 0a   present in the.
18540 2a 2a 20 73 6f 72 74 65 64 20 72 65 63 6f 72 64  ** sorted record
18550 73 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53  s. However, if S
18560 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
18570 20 62 61 73 65 64 20 6f 6e 20 74 68 65 20 64 65   based on the de
18580 63 6c 61 72 65 64 20 74 79 70 65 0a 2a 2a 20 6f  clared type.** o
18590 66 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  f a table column
185a0 20 74 68 61 74 20 69 74 73 20 76 61 6c 75 65 73   that its values
185b0 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62   are likely to b
185c0 65 20 76 65 72 79 20 6c 61 72 67 65 20 2d 20 6c  e very large - l
185d0 61 72 67 65 72 0a 2a 2a 20 74 68 61 6e 20 74 68  arger.** than th
185e0 65 20 63 6f 6e 66 69 67 75 72 65 64 20 73 6f 72  e configured sor
185f0 74 65 72 2d 72 65 66 65 72 65 6e 63 65 20 73 69  ter-reference si
18600 7a 65 20 74 68 72 65 73 68 6f 6c 64 20 2d 20 74  ze threshold - t
18610 68 65 6e 20 61 20 72 65 66 65 72 65 6e 63 65 0a  hen a reference.
18620 2a 2a 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  ** is stored in 
18630 65 61 63 68 20 73 6f 72 74 65 64 20 72 65 63 6f  each sorted reco
18640 72 64 20 61 6e 64 20 74 68 65 20 72 65 71 75 69  rd and the requi
18650 72 65 64 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  red column value
18660 73 20 6c 6f 61 64 65 64 0a 2a 2a 20 66 72 6f 6d  s loaded.** from
18670 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 73   the database as
18680 20 72 65 63 6f 72 64 73 20 61 72 65 20 72 65 74   records are ret
18690 75 72 6e 65 64 20 69 6e 20 73 6f 72 74 65 64 20  urned in sorted 
186a0 6f 72 64 65 72 2e 20 54 68 65 20 64 65 66 61 75  order. The defau
186b0 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 66 6f 72 20  lt.** value for 
186c0 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 74  this option is t
186d0 6f 20 6e 65 76 65 72 20 75 73 65 20 74 68 69 73  o never use this
186e0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 53   optimization. S
186f0 70 65 63 69 66 79 69 6e 67 20 61 20 0a 2a 2a 20  pecifying a .** 
18700 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66  negative value f
18710 6f 72 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 72  or this option r
18720 65 73 74 6f 72 65 73 20 74 68 65 20 64 65 66 61  estores the defa
18730 75 6c 74 20 62 65 68 61 76 69 6f 75 72 2e 0a 2a  ult behaviour..*
18740 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  * This option is
18750 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
18760 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
18770 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
18780 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
18790 5f 53 4f 52 54 45 52 5f 52 45 46 45 52 45 4e 43  _SORTER_REFERENC
187a0 45 53 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ES] compile-time
187b0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b   option..**.** [
187c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
187d0 45 4d 44 42 5f 4d 41 58 53 49 5a 45 5d 5d 0a 2a  EMDB_MAXSIZE]].*
187e0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
187f0 46 49 47 5f 4d 45 4d 44 42 5f 4d 41 58 53 49 5a  FIG_MEMDB_MAXSIZ
18800 45 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c  E.** <dd>The SQL
18810 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 44 42  ITE_CONFIG_MEMDB
18820 5f 4d 41 58 53 49 5a 45 20 6f 70 74 69 6f 6e 20  _MAXSIZE option 
18830 61 63 63 65 70 74 73 20 61 20 73 69 6e 67 6c 65  accepts a single
18840 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 5b 73   parameter.** [s
18850 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d 20 70 61  qlite3_int64] pa
18860 72 61 6d 65 74 65 72 20 77 68 69 63 68 20 69 73  rameter which is
18870 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 61 78   the default max
18880 69 6d 75 6d 20 73 69 7a 65 20 66 6f 72 20 61 6e  imum size for an
18890 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 64 61   in-memory.** da
188a0 74 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75  tabase created u
188b0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 64 65  sing [sqlite3_de
188c0 73 65 72 69 61 6c 69 7a 65 28 29 5d 2e 20 20 54  serialize()].  T
188d0 68 69 73 20 64 65 66 61 75 6c 74 20 6d 61 78 69  his default maxi
188e0 6d 75 6d 0a 2a 2a 20 73 69 7a 65 20 63 61 6e 20  mum.** size can 
188f0 62 65 20 61 64 6a 75 73 74 65 64 20 75 70 20 6f  be adjusted up o
18900 72 20 64 6f 77 6e 20 66 6f 72 20 69 6e 64 69 76  r down for indiv
18910 69 64 75 61 6c 20 64 61 74 61 62 61 73 65 73 20  idual databases 
18920 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51  using the.** [SQ
18930 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
18940 4c 49 4d 49 54 5d 20 5b 73 71 6c 69 74 65 33 5f  LIMIT] [sqlite3_
18950 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 7c 66 69 6c  file_control|fil
18960 65 2d 63 6f 6e 74 72 6f 6c 5d 2e 20 20 49 66 20  e-control].  If 
18970 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  this.** configur
18980 61 74 69 6f 6e 20 73 65 74 74 69 6e 67 20 69 73  ation setting is
18990 20 6e 65 76 65 72 20 75 73 65 64 2c 20 74 68 65   never used, the
189a0 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 61  n the default ma
189b0 78 69 6d 75 6d 20 69 73 20 64 65 74 65 72 6d 69  ximum is determi
189c0 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53  ned.** by the [S
189d0 51 4c 49 54 45 5f 4d 45 4d 44 42 5f 44 45 46 41  QLITE_MEMDB_DEFA
189e0 55 4c 54 5f 4d 41 58 53 49 5a 45 5d 20 63 6f 6d  ULT_MAXSIZE] com
189f0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
18a00 2e 20 20 49 66 20 74 68 61 74 0a 2a 2a 20 63 6f  .  If that.** co
18a10 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
18a20 6e 20 69 73 20 6e 6f 74 20 73 65 74 2c 20 74 68  n is not set, th
18a30 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  en the default m
18a40 61 78 69 6d 75 6d 20 69 73 20 31 30 37 33 37 34  aximum is 107374
18a50 31 38 32 34 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  1824..** </dl>.*
18a60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18a70 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
18a80 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
18a90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18aa0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
18ab0 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
18ac0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18ad0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
18ae0 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
18af0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
18b00 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
18b10 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
18b20 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
18b30 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
18b40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
18b50 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
18b60 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
18b70 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
18b80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
18b90 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
18ba0 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
18bb0 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
18bc0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
18bd0 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
18be0 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
18bf0 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
18c00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
18c10 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
18c20 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
18c30 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
18c40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18c50 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
18c60 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
18c70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18c80 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
18c90 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
18ca0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
18cb0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
18cc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
18cd0 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
18ce0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
18cf0 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72  ethods* */./* pr
18d00 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f  eviously SQLITE_
18d10 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f  CONFIG_CHUNKALLO
18d20 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f  C 12 which is no
18d30 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64  w unused. */ .#d
18d40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18d50 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
18d60 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20   13  /* int int 
18d70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18d80 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
18d90 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d        14  /* no-
18da0 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
18db0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
18dc0 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20  CACHE    15  /* 
18dd0 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
18de0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
18df0 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
18e00 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
18e10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18e20 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20  E_CONFIG_URI    
18e30 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74        17  /* int
18e40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18e50 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
18e60 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71  2      18  /* sq
18e70 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
18e80 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
18e90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18ea0 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20  GETPCACHE2   19 
18eb0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
18ec0 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
18ed0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18ee0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
18ef0 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a  NDEX_SCAN 20  /*
18f00 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
18f10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
18f20 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f  LLOG       21  /
18f30 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a  * xSqllog, void*
18f40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18f50 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
18f60 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71  IZE    22  /* sq
18f70 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c  lite3_int64, sql
18f80 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64  ite3_int64 */.#d
18f90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18fa0 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
18fb0 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69  ZE      23  /* i
18fc0 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66  nt nByte */.#def
18fd0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18fe0 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20  G_PCACHE_HDRSZ  
18ff0 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74        24  /* int
19000 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65   *psz */.#define
19010 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
19020 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20 20  MASZ            
19030 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e     25  /* unsign
19040 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a  ed int szPma */.
19050 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
19060 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53  ONFIG_STMTJRNL_S
19070 50 49 4c 4c 20 20 20 20 20 20 32 36 20 20 2f 2a  PILL      26  /*
19080 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64   int nByte */.#d
19090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
190a0 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43  FIG_SMALL_MALLOC
190b0 20 20 20 20 20 20 20 20 32 37 20 20 2f 2a 20 62          27  /* b
190c0 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
190d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
190e0 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 20 20  SORTERREF_SIZE  
190f0 20 20 20 20 32 38 20 20 2f 2a 20 69 6e 74 20 6e      28  /* int n
19100 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Byte */.#define 
19110 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
19120 4d 44 42 5f 4d 41 58 53 49 5a 45 20 20 20 20 20  MDB_MAXSIZE     
19130 20 20 32 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    29  /* sqlite3
19140 5f 69 6e 74 36 34 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  _int64 */../*.**
19150 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
19160 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43  ase Connection C
19170 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
19180 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
19190 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
191a0 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
191b0 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
191c0 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
191d0 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
191e0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
191f0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
19200 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
19210 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
19220 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
19230 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
19240 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
19250 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
19260 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
19270 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
19280 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
19290 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
192a0 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
192b0 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
192c0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
192d0 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
192e0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
192f0 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
19300 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
19310 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  d.  ^The [sqlite
19320 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
19330 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
19340 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
19350 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
19360 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
19370 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
19380 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
19390 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
193a0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
193b0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f  ** [[SQLITE_DBCO
193c0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d  NFIG_LOOKASIDE]]
193d0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
193e0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
193f0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
19400 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
19410 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
19420 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
19430 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
19440 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
19450 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
19460 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
19470 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
19480 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
19490 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
194a0 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
194b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
194c0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
194d0 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
194e0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
194f0 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
19500 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
19510 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
19520 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
19530 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
19540 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
19550 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
19560 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
19570 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
19580 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
19590 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
195a0 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
195b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
195c0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
195d0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
195e0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
195f0 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
19600 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
19610 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
19620 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
19630 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
19640 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
19650 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
19660 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
19670 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
19680 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
19690 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
196a0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
196b0 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
196c0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
196d0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
196e0 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
196f0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
19700 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
19710 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
19720 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
19730 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
19740 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
19750 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
19760 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
19770 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
19780 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
19790 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
197a0 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
197b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
197c0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
197d0 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
197e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
197f0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
19800 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
19810 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
19820 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
19830 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
19840 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
19850 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
19860 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
19870 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
19880 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
19890 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
198a0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
198b0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
198c0 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
198d0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
198e0 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
198f0 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
19900 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
19910 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
19920 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
19930 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  )^</dd>.**.** [[
19940 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19950 45 4e 41 42 4c 45 5f 46 4b 45 59 5d 5d 0a 2a 2a  ENABLE_FKEY]].**
19960 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
19970 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
19980 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
19990 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
199a0 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
199b0 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f  disable the enfo
199c0 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66  rcement of.** [f
199d0 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74  oreign key const
199e0 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20  raints].  There 
199f0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
19a00 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
19a10 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
19a20 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
19a30 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
19a40 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b   0 to disable FK
19a50 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a   enforcement,.**
19a60 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
19a70 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
19a80 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  nt or negative t
19a90 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72  o leave FK enfor
19aa0 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e  cement.** unchan
19ab0 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ged.  The second
19ac0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
19ad0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
19ae0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
19af0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
19b00 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
19b10 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66  e whether FK enf
19b20 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20  orcement is off 
19b30 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  or on.** followi
19b40 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
19b50 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
19b60 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
19b70 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
19b80 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
19b90 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73  FK enforcement s
19ba0 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
19bb0 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
19bc0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
19bd0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
19be0 45 5f 54 52 49 47 47 45 52 5d 5d 0a 2a 2a 20 3c  E_TRIGGER]].** <
19bf0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
19c00 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
19c10 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
19c20 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
19c30 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
19c40 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45   disable [CREATE
19c50 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
19c60 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  ers]..** There s
19c70 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
19c80 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
19c90 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
19ca0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
19cb0 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
19cc0 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69  0 to disable tri
19cd0 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69  ggers,.** positi
19ce0 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69  ve to enable tri
19cf0 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76  ggers or negativ
19d00 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
19d10 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
19d20 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
19d30 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
19d40 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
19d50 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
19d60 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
19d70 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
19d80 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72   whether trigger
19d90 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f  s are disabled o
19da0 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
19db0 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
19dc0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
19dd0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
19de0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
19df0 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
19e00 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74  the trigger sett
19e10 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
19e20 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
19e30 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44  **.** [[SQLITE_D
19e40 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
19e50 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 5d 5d 0a  TS3_TOKENIZER]].
19e60 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
19e70 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54  CONFIG_ENABLE_FT
19e80 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74  S3_TOKENIZER</dt
19e90 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
19ea0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
19eb0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
19ec0 62 6c 65 20 74 68 65 0a 2a 2a 20 5b 66 74 73 33  ble the.** [fts3
19ed0 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75  _tokenizer()] fu
19ee0 6e 63 74 69 6f 6e 20 77 68 69 63 68 20 69 73 20  nction which is 
19ef0 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  part of the.** [
19f00 46 54 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20  FTS3] full-text 
19f10 73 65 61 72 63 68 20 65 6e 67 69 6e 65 20 65 78  search engine ex
19f20 74 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72  tension..** Ther
19f30 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
19f40 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
19f50 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
19f60 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
19f70 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
19f80 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
19f90 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29  fts3_tokenizer()
19fa0 20 6f 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20   or.** positive 
19fb0 74 6f 20 65 6e 61 62 6c 65 20 66 74 73 33 5f 74  to enable fts3_t
19fc0 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65  okenizer() or ne
19fd0 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
19fe0 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75  the setting.** u
19ff0 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
1a000 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1a010 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
1a020 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
1a030 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
1a040 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
1a050 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
1a060 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20   fts3_tokenizer 
1a070 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  is disabled or e
1a080 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
1a090 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
1a0a0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1a0b0 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
1a0c0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
1a0d0 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
1a0e0 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20   new setting is 
1a0f0 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
1a100 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  k. </dd>.**.** [
1a110 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
1a120 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54  _ENABLE_LOAD_EXT
1a130 45 4e 53 49 4f 4e 5d 5d 0a 2a 2a 20 3c 64 74 3e  ENSION]].** <dt>
1a140 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1a150 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45  ENABLE_LOAD_EXTE
1a160 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  NSION</dt>.** <d
1a170 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
1a180 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
1a190 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
1a1a0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
1a1b0 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69  xtension()].** i
1a1c0 6e 74 65 72 66 61 63 65 20 69 6e 64 65 70 65 6e  nterface indepen
1a1d0 64 65 6e 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c  dently of the [l
1a1e0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
1a1f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   SQL function..*
1a200 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  * The [sqlite3_e
1a210 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
1a220 73 69 6f 6e 28 29 5d 20 41 50 49 20 65 6e 61 62  sion()] API enab
1a230 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
1a240 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50  both the.** C-AP
1a250 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  I [sqlite3_load_
1a260 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64  extension()] and
1a270 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
1a280 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  n [load_extensio
1a290 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  n()]..** There s
1a2a0 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
1a2b0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
1a2c0 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 66  s..** When the f
1a2d0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1a2e0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
1a2f0 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20  is 1, then only 
1a300 74 68 65 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20  the C-API is.** 
1a310 65 6e 61 62 6c 65 64 20 61 6e 64 20 74 68 65 20  enabled and the 
1a320 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d  SQL function rem
1a330 61 69 6e 73 20 64 69 73 61 62 6c 65 64 2e 20 20  ains disabled.  
1a340 49 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67  If the first arg
1a350 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73  ument to.** this
1a360 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 30 2c   interface is 0,
1a370 20 74 68 65 6e 20 62 6f 74 68 20 74 68 65 20 43   then both the C
1a380 2d 41 50 49 20 61 6e 64 20 74 68 65 20 53 51 4c  -API and the SQL
1a390 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 64 69   function are di
1a3a0 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68  sabled..** If th
1a3b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1a3c0 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20   is -1, then no 
1a3d0 63 68 61 6e 67 65 73 20 61 72 65 20 6d 61 64 65  changes are made
1a3e0 20 74 6f 20 73 74 61 74 65 20 6f 66 20 65 69 74   to state of eit
1a3f0 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49  her the.** C-API
1a400 20 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63   or the SQL func
1a410 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63  tion..** The sec
1a420 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
1a430 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
1a440 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
1a450 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
1a460 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
1a470 63 61 74 65 20 77 68 65 74 68 65 72 20 5b 73 71  cate whether [sq
1a480 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
1a490 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63  sion()] interfac
1a4a0 65 0a 2a 2a 20 69 73 20 64 69 73 61 62 6c 65 64  e.** is disabled
1a4b0 20 6f 72 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c   or enabled foll
1a4c0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
1a4d0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
1a4e0 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65  ameter may.** be
1a4f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
1a500 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74   in which case t
1a510 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69  he new setting i
1a520 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
1a530 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ack..** </dd>.**
1a540 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43  .** [[SQLITE_DBC
1a550 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45  ONFIG_MAINDBNAME
1a560 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ]] <dt>SQLITE_DB
1a570 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d  CONFIG_MAINDBNAM
1a580 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
1a590 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
1a5a0 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68  sed to change th
1a5b0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 22 6d  e name of the "m
1a5c0 61 69 6e 22 20 64 61 74 61 62 61 73 65 0a 2a 2a  ain" database.**
1a5d0 20 73 63 68 65 6d 61 2e 20 20 5e 54 68 65 20 73   schema.  ^The s
1a5e0 6f 6c 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ole argument is 
1a5f0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63  a pointer to a c
1a600 6f 6e 73 74 61 6e 74 20 55 54 46 38 20 73 74 72  onstant UTF8 str
1a610 69 6e 67 0a 2a 2a 20 77 68 69 63 68 20 77 69 6c  ing.** which wil
1a620 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 6e 65 77  l become the new
1a630 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 69 6e 20   schema name in 
1a640 70 6c 61 63 65 20 6f 66 20 22 6d 61 69 6e 22 2e  place of "main".
1a650 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65    ^SQLite.** doe
1a660 73 20 6e 6f 74 20 6d 61 6b 65 20 61 20 63 6f 70  s not make a cop
1a670 79 20 6f 66 20 74 68 65 20 6e 65 77 20 6d 61 69  y of the new mai
1a680 6e 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 73 74  n schema name st
1a690 72 69 6e 67 2c 20 73 6f 20 74 68 65 20 61 70 70  ring, so the app
1a6a0 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  lication.** must
1a6b0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1a6c0 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
1a6d0 20 69 6e 74 6f 20 74 68 69 73 20 44 42 43 4f 4e   into this DBCON
1a6e0 46 49 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  FIG option is un
1a6f0 63 68 61 6e 67 65 64 0a 2a 2a 20 75 6e 74 69 6c  changed.** until
1a700 20 61 66 74 65 72 20 74 68 65 20 64 61 74 61 62   after the datab
1a710 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
1a720 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  loses..** </dd>.
1a730 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44  **.** [[SQLITE_D
1a740 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f  BCONFIG_NO_CKPT_
1a750 4f 4e 5f 43 4c 4f 53 45 5d 5d 20 0a 2a 2a 20 3c  ON_CLOSE]] .** <
1a760 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
1a770 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c  IG_NO_CKPT_ON_CL
1a780 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  OSE</dt>.** <dd>
1a790 20 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20 61   Usually, when a
1a7a0 20 64 61 74 61 62 61 73 65 20 69 6e 20 77 61 6c   database in wal
1a7b0 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73 65 64 20   mode is closed 
1a7c0 6f 72 20 64 65 74 61 63 68 65 64 20 66 72 6f 6d  or detached from
1a7d0 20 61 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20   a .** database 
1a7e0 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74 65 20 63  handle, SQLite c
1a7f0 68 65 63 6b 73 20 69 66 20 74 68 69 73 20 77 69  hecks if this wi
1a800 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ll mean that the
1a810 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f 20 0a 2a  re are now no .*
1a820 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61 74  * connections at
1a830 20 61 6c 6c 20 74 6f 20 74 68 65 20 64 61 74 61   all to the data
1a840 62 61 73 65 2e 20 49 66 20 73 6f 2c 20 69 74 20  base. If so, it 
1a850 70 65 72 66 6f 72 6d 73 20 61 20 63 68 65 63 6b  performs a check
1a860 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65 72 61 74  point .** operat
1a870 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c 6f 73 69  ion before closi
1a880 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ng the connectio
1a890 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 6d  n. This option m
1a8a0 61 79 20 62 65 20 75 73 65 64 20 74 6f 0a 2a 2a  ay be used to.**
1a8b0 20 6f 76 65 72 72 69 64 65 20 74 68 69 73 20 62   override this b
1a8c0 65 68 61 76 69 6f 75 72 2e 20 54 68 65 20 66 69  ehaviour. The fi
1a8d0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 70 61  rst parameter pa
1a8e0 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f 70 65  ssed to this ope
1a8f0 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 61 6e 20  ration.** is an 
1a900 69 6e 74 65 67 65 72 20 2d 20 70 6f 73 69 74 69  integer - positi
1a910 76 65 20 74 6f 20 64 69 73 61 62 6c 65 20 63 68  ve to disable ch
1a920 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f  eckpoints-on-clo
1a930 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28 74 68 65  se, or zero (the
1a940 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20 74 6f 20  .** default) to 
1a950 65 6e 61 62 6c 65 20 74 68 65 6d 2c 20 61 6e 64  enable them, and
1a960 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
1a970 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75  ve the setting u
1a980 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
1a990 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1a9a0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
1a9b0 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  o an integer.** 
1a9c0 69 6e 74 6f 20 77 68 69 63 68 20 69 73 20 77 72  into which is wr
1a9d0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
1a9e0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
1a9f0 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d   checkpoints-on-
1aa00 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65 20 62 65  close.** have be
1aa10 65 6e 20 64 69 73 61 62 6c 65 64 20 2d 20 30 20  en disabled - 0 
1aa20 69 66 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  if they are not 
1aa30 64 69 73 61 62 6c 65 64 2c 20 31 20 69 66 20 74  disabled, 1 if t
1aa40 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c 2f 64 64  hey are..** </dd
1aa50 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
1aa60 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
1aa70 5f 51 50 53 47 5d 5d 20 3c 64 74 3e 53 51 4c 49  _QPSG]] <dt>SQLI
1aa80 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
1aa90 4c 45 5f 51 50 53 47 3c 2f 64 74 3e 0a 2a 2a 20  LE_QPSG</dt>.** 
1aaa0 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45  <dd>^(The SQLITE
1aab0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
1aac0 5f 51 50 53 47 20 6f 70 74 69 6f 6e 20 61 63 74  _QPSG option act
1aad0 69 76 61 74 65 73 20 6f 72 20 64 65 61 63 74 69  ivates or deacti
1aae0 76 61 74 65 73 0a 2a 2a 20 74 68 65 20 5b 71 75  vates.** the [qu
1aaf0 65 72 79 20 70 6c 61 6e 6e 65 72 20 73 74 61 62  ery planner stab
1ab00 69 6c 69 74 79 20 67 75 61 72 61 6e 74 65 65 5d  ility guarantee]
1ab10 20 28 51 50 53 47 29 2e 20 20 57 68 65 6e 20 74   (QPSG).  When t
1ab20 68 65 20 51 50 53 47 20 69 73 20 61 63 74 69 76  he QPSG is activ
1ab30 65 2c 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 20 53  e,.** a single S
1ab40 51 4c 20 71 75 65 72 79 20 73 74 61 74 65 6d 65  QL query stateme
1ab50 6e 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 75  nt will always u
1ab60 73 65 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  se the same algo
1ab70 72 69 74 68 6d 20 72 65 67 61 72 64 6c 65 73 73  rithm regardless
1ab80 0a 2a 2a 20 6f 66 20 76 61 6c 75 65 73 20 6f 66  .** of values of
1ab90 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65   [bound paramete
1aba0 72 73 5d 2e 29 5e 20 54 68 65 20 51 50 53 47 20  rs].)^ The QPSG 
1abb0 64 69 73 61 62 6c 65 73 20 73 6f 6d 65 20 71 75  disables some qu
1abc0 65 72 79 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ery optimization
1abd0 73 0a 2a 2a 20 74 68 61 74 20 6c 6f 6f 6b 20 61  s.** that look a
1abe0 74 20 74 68 65 20 76 61 6c 75 65 73 20 6f 66 20  t the values of 
1abf0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
1ac00 2c 20 77 68 69 63 68 20 63 61 6e 20 6d 61 6b 65  , which can make
1ac10 20 73 6f 6d 65 20 71 75 65 72 69 65 73 0a 2a 2a   some queries.**
1ac20 20 73 6c 6f 77 65 72 2e 20 20 42 75 74 20 74 68   slower.  But th
1ac30 65 20 51 50 53 47 20 68 61 73 20 74 68 65 20 61  e QPSG has the a
1ac40 64 76 61 6e 74 61 67 65 20 6f 66 20 6d 6f 72 65  dvantage of more
1ac50 20 70 72 65 64 69 63 74 61 62 6c 65 20 62 65 68   predictable beh
1ac60 61 76 69 6f 72 2e 20 20 57 69 74 68 0a 2a 2a 20  avior.  With.** 
1ac70 74 68 65 20 51 50 53 47 20 61 63 74 69 76 65 2c  the QPSG active,
1ac80 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77   SQLite will alw
1ac90 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d 65  ays use the same
1aca0 20 71 75 65 72 79 20 70 6c 61 6e 20 69 6e 20 74   query plan in t
1acb0 68 65 20 66 69 65 6c 64 20 61 73 0a 2a 2a 20 77  he field as.** w
1acc0 61 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  as used during t
1acd0 65 73 74 69 6e 67 20 69 6e 20 74 68 65 20 6c 61  esting in the la
1ace0 62 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  b..** The first 
1acf0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
1ad00 20 73 65 74 74 69 6e 67 20 69 73 20 61 6e 20 69   setting is an i
1ad10 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
1ad20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 0a 2a 2a  0 to disable .**
1ad30 20 74 68 65 20 51 50 53 47 2c 20 70 6f 73 69 74   the QPSG, posit
1ad40 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 51 50  ive to enable QP
1ad50 53 47 2c 20 6f 72 20 6e 65 67 61 74 69 76 65 20  SG, or negative 
1ad60 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
1ad70 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65  ting.** unchange
1ad80 64 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  d. The second pa
1ad90 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
1ada0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
1adb0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
1adc0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
1add0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
1ade0 68 65 74 68 65 72 20 74 68 65 20 51 50 53 47 20  hether the QPSG 
1adf0 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  is disabled or e
1ae00 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
1ae10 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 0a 2a  ing this call..*
1ae20 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
1ae30 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1ae40 54 52 49 47 47 45 52 5f 45 51 50 5d 5d 20 3c 64  TRIGGER_EQP]] <d
1ae50 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
1ae60 47 5f 54 52 49 47 47 45 52 5f 45 51 50 3c 2f 64  G_TRIGGER_EQP</d
1ae70 74 3e 0a 2a 2a 20 3c 64 64 3e 20 42 79 20 64 65  t>.** <dd> By de
1ae80 66 61 75 6c 74 2c 20 74 68 65 20 6f 75 74 70 75  fault, the outpu
1ae90 74 20 6f 66 20 45 58 50 4c 41 49 4e 20 51 55 45  t of EXPLAIN QUE
1aea0 52 59 20 50 4c 41 4e 20 63 6f 6d 6d 61 6e 64 73  RY PLAN commands
1aeb0 20 64 6f 65 73 20 6e 6f 74 20 0a 2a 2a 20 69 6e   does not .** in
1aec0 63 6c 75 64 65 20 6f 75 74 70 75 74 20 66 6f 72  clude output for
1aed0 20 61 6e 79 20 6f 70 65 72 61 74 69 6f 6e 73 20   any operations 
1aee0 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 72 69  performed by tri
1aef0 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 54  gger programs. T
1af00 68 69 73 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73  his.** option is
1af10 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
1af20 63 6c 65 61 72 20 28 74 68 65 20 64 65 66 61 75  clear (the defau
1af30 6c 74 29 20 61 20 66 6c 61 67 20 74 68 61 74 20  lt) a flag that 
1af40 67 6f 76 65 72 6e 73 20 74 68 69 73 0a 2a 2a 20  governs this.** 
1af50 62 65 68 61 76 69 6f 72 2e 20 54 68 65 20 66 69  behavior. The fi
1af60 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 70 61  rst parameter pa
1af70 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f 70 65  ssed to this ope
1af80 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 69 6e 74  ration is an int
1af90 65 67 65 72 20 2d 0a 2a 2a 20 70 6f 73 69 74 69  eger -.** positi
1afa0 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 6f 75 74  ve to enable out
1afb0 70 75 74 20 66 6f 72 20 74 72 69 67 67 65 72 20  put for trigger 
1afc0 70 72 6f 67 72 61 6d 73 2c 20 6f 72 20 7a 65 72  programs, or zer
1afd0 6f 20 74 6f 20 64 69 73 61 62 6c 65 20 69 74 2c  o to disable it,
1afe0 0a 2a 2a 20 6f 72 20 6e 65 67 61 74 69 76 65 20  .** or negative 
1aff0 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
1b000 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
1b010 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
1b020 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
1b030 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
1b040 65 72 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73  er into which is
1b050 20 77 72 69 74 74 65 6e 20 0a 2a 2a 20 30 20 6f   written .** 0 o
1b060 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
1b070 77 68 65 74 68 65 72 20 6f 75 74 70 75 74 2d 66  whether output-f
1b080 6f 72 2d 74 72 69 67 67 65 72 73 20 68 61 73 20  or-triggers has 
1b090 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d 20  been disabled - 
1b0a0 30 20 69 66 20 0a 2a 2a 20 69 74 20 69 73 20 6e  0 if .** it is n
1b0b0 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69  ot disabled, 1 i
1b0c0 66 20 69 74 20 69 73 2e 20 20 0a 2a 2a 20 3c 2f  f it is.  .** </
1b0d0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
1b0e0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45  TE_DBCONFIG_RESE
1b0f0 54 5f 44 41 54 41 42 41 53 45 5d 5d 20 3c 64 74  T_DATABASE]] <dt
1b100 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
1b110 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 3c  _RESET_DATABASE<
1b120 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 53 65 74  /dt>.** <dd> Set
1b130 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f   the SQLITE_DBCO
1b140 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41 42  NFIG_RESET_DATAB
1b150 41 53 45 20 66 6c 61 67 20 61 6e 64 20 74 68 65  ASE flag and the
1b160 6e 20 72 75 6e 0a 2a 2a 20 5b 56 41 43 55 55 4d  n run.** [VACUUM
1b170 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65  ] in order to re
1b180 73 65 74 20 61 20 64 61 74 61 62 61 73 65 20 62  set a database b
1b190 61 63 6b 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  ack to an empty 
1b1a0 64 61 74 61 62 61 73 65 0a 2a 2a 20 77 69 74 68  database.** with
1b1b0 20 6e 6f 20 73 63 68 65 6d 61 20 61 6e 64 20 6e   no schema and n
1b1c0 6f 20 63 6f 6e 74 65 6e 74 2e 20 54 68 65 20 66  o content. The f
1b1d0 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 63 65 73 73  ollowing process
1b1e0 20 77 6f 72 6b 73 20 65 76 65 6e 20 66 6f 72 0a   works even for.
1b1f0 2a 2a 20 61 20 62 61 64 6c 79 20 63 6f 72 72 75  ** a badly corru
1b200 70 74 65 64 20 64 61 74 61 62 61 73 65 20 66 69  pted database fi
1b210 6c 65 3a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  le:.** <ol>.** <
1b220 6c 69 3e 20 49 66 20 74 68 65 20 64 61 74 61 62  li> If the datab
1b230 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1b240 73 20 6e 65 77 6c 79 20 6f 70 65 6e 65 64 2c 20  s newly opened, 
1b250 6d 61 6b 65 20 73 75 72 65 20 69 74 20 68 61 73  make sure it has
1b260 20 72 65 61 64 20 74 68 65 0a 2a 2a 20 20 20 20   read the.**    
1b270 20 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d    database schem
1b280 61 20 62 79 20 70 72 65 70 61 72 69 6e 67 20 74  a by preparing t
1b290 68 65 6e 20 64 69 73 63 61 72 64 69 6e 67 20 73  hen discarding s
1b2a0 6f 6d 65 20 71 75 65 72 79 20 61 67 61 69 6e 73  ome query agains
1b2b0 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 64 61  t the.**      da
1b2c0 74 61 62 61 73 65 2c 20 6f 72 20 63 61 6c 6c 69  tabase, or calli
1b2d0 6e 67 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65  ng sqlite3_table
1b2e0 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61  _column_metadata
1b2f0 28 29 2c 20 69 67 6e 6f 72 69 6e 67 20 61 6e 79  (), ignoring any
1b300 0a 2a 2a 20 20 20 20 20 20 65 72 72 6f 72 73 2e  .**      errors.
1b310 20 20 54 68 69 73 20 73 74 65 70 20 69 73 20 6f    This step is o
1b320 6e 6c 79 20 6e 65 63 65 73 73 61 72 79 20 69 66  nly necessary if
1b330 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1b340 20 64 65 73 69 72 65 73 20 74 6f 20 6b 65 65 70   desires to keep
1b350 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 64 61 74  .**      the dat
1b360 61 62 61 73 65 20 69 6e 20 57 41 4c 20 6d 6f 64  abase in WAL mod
1b370 65 20 61 66 74 65 72 20 74 68 65 20 72 65 73 65  e after the rese
1b380 74 20 69 66 20 69 74 20 77 61 73 20 69 6e 20 57  t if it was in W
1b390 41 4c 20 6d 6f 64 65 20 62 65 66 6f 72 65 0a 2a  AL mode before.*
1b3a0 2a 20 20 20 20 20 20 74 68 65 20 72 65 73 65 74  *      the reset
1b3b0 2e 20 20 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69  .  .** <li> sqli
1b3c0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 64 62  te3_db_config(db
1b3d0 2c 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  , SQLITE_DBCONFI
1b3e0 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 45  G_RESET_DATABASE
1b3f0 2c 20 31 2c 20 30 29 3b 0a 2a 2a 20 3c 6c 69 3e  , 1, 0);.** <li>
1b400 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 5d 28   [sqlite3_exec](
1b410 64 62 2c 20 22 5b 56 41 43 55 55 4d 5d 22 2c 20  db, "[VACUUM]", 
1b420 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 3c 6c 69  0, 0, 0);.** <li
1b430 3e 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  > sqlite3_db_con
1b440 66 69 67 28 64 62 2c 20 53 51 4c 49 54 45 5f 44  fig(db, SQLITE_D
1b450 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41  BCONFIG_RESET_DA
1b460 54 41 42 41 53 45 2c 20 30 2c 20 30 29 3b 0a 2a  TABASE, 0, 0);.*
1b470 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 20 42 65 63 61 75  * </ol>.** Becau
1b480 73 65 20 72 65 73 65 74 74 69 6e 67 20 61 20 64  se resetting a d
1b490 61 74 61 62 61 73 65 20 69 73 20 64 65 73 74 72  atabase is destr
1b4a0 75 63 74 69 76 65 20 61 6e 64 20 69 72 72 65 76  uctive and irrev
1b4b0 65 72 73 69 62 6c 65 2c 20 74 68 65 0a 2a 2a 20  ersible, the.** 
1b4c0 70 72 6f 63 65 73 73 20 72 65 71 75 69 72 65 73  process requires
1b4d0 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 69 73   the use of this
1b4e0 20 6f 62 73 63 75 72 65 20 41 50 49 20 61 6e 64   obscure API and
1b4f0 20 6d 75 6c 74 69 70 6c 65 20 73 74 65 70 73 20   multiple steps 
1b500 74 6f 20 68 65 6c 70 0a 2a 2a 20 65 6e 73 75 72  to help.** ensur
1b510 65 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e  e that it does n
1b520 6f 74 20 68 61 70 70 65 6e 20 62 79 20 61 63 63  ot happen by acc
1b530 69 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ident..**.** [[S
1b540 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44  QLITE_DBCONFIG_D
1b550 45 46 45 4e 53 49 56 45 5d 5d 20 3c 64 74 3e 53  EFENSIVE]] <dt>S
1b560 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44  QLITE_DBCONFIG_D
1b570 45 46 45 4e 53 49 56 45 3c 2f 64 74 3e 0a 2a 2a  EFENSIVE</dt>.**
1b580 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f   <dd>The SQLITE_
1b590 44 42 43 4f 4e 46 49 47 5f 44 45 46 45 4e 53 49  DBCONFIG_DEFENSI
1b5a0 56 45 20 6f 70 74 69 6f 6e 20 61 63 74 69 76 61  VE option activa
1b5b0 74 65 73 20 6f 72 20 64 65 61 63 74 69 76 61 74  tes or deactivat
1b5c0 65 73 20 74 68 65 0a 2a 2a 20 22 64 65 66 65 6e  es the.** "defen
1b5d0 73 69 76 65 22 20 66 6c 61 67 20 66 6f 72 20 61  sive" flag for a
1b5e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1b5f0 74 69 6f 6e 2e 20 20 57 68 65 6e 20 74 68 65 20  tion.  When the 
1b600 64 65 66 65 6e 73 69 76 65 0a 2a 2a 20 66 6c 61  defensive.** fla
1b610 67 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 6c 61  g is enabled, la
1b620 6e 67 75 61 67 65 20 66 65 61 74 75 72 65 73 20  nguage features 
1b630 74 68 61 74 20 61 6c 6c 6f 77 20 6f 72 64 69 6e  that allow ordin
1b640 61 72 79 20 53 51 4c 20 74 6f 20 0a 2a 2a 20 64  ary SQL to .** d
1b650 65 6c 69 62 65 72 61 74 65 6c 79 20 63 6f 72 72  eliberately corr
1b660 75 70 74 20 74 68 65 20 64 61 74 61 62 61 73 65  upt the database
1b670 20 66 69 6c 65 20 61 72 65 20 64 69 73 61 62 6c   file are disabl
1b680 65 64 2e 20 20 54 68 65 20 64 69 73 61 62 6c 65  ed.  The disable
1b690 64 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 69 6e  d.** features in
1b6a0 63 6c 75 64 65 20 62 75 74 20 61 72 65 20 6e 6f  clude but are no
1b6b0 74 20 6c 69 6d 69 74 65 64 20 74 6f 20 74 68 65  t limited to the
1b6c0 20 66 6f 6c 6c 6f 77 69 6e 67 3a 0a 2a 2a 20 3c   following:.** <
1b6d0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
1b6e0 5b 50 52 41 47 4d 41 20 77 72 69 74 61 62 6c 65  [PRAGMA writable
1b6f0 5f 73 63 68 65 6d 61 3d 4f 4e 5d 20 73 74 61 74  _schema=ON] stat
1b700 65 6d 65 6e 74 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  ement..** <li> T
1b710 68 65 20 5b 50 52 41 47 4d 41 20 6a 6f 75 72 6e  he [PRAGMA journ
1b720 61 6c 5f 6d 6f 64 65 3d 4f 46 46 5d 20 73 74 61  al_mode=OFF] sta
1b730 74 65 6d 65 6e 74 2e 0a 2a 2a 20 3c 6c 69 3e 20  tement..** <li> 
1b740 57 72 69 74 65 73 20 74 6f 20 74 68 65 20 5b 73  Writes to the [s
1b750 71 6c 69 74 65 5f 64 62 70 61 67 65 5d 20 76 69  qlite_dbpage] vi
1b760 72 74 75 61 6c 20 74 61 62 6c 65 2e 0a 2a 2a 20  rtual table..** 
1b770 3c 6c 69 3e 20 44 69 72 65 63 74 20 77 72 69 74  <li> Direct writ
1b780 65 73 20 74 6f 20 5b 73 68 61 64 6f 77 20 74 61  es to [shadow ta
1b790 62 6c 65 73 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  bles]..** </ul>.
1b7a0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
1b7b0 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
1b7c0 5f 57 52 49 54 41 42 4c 45 5f 53 43 48 45 4d 41  _WRITABLE_SCHEMA
1b7d0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ]] <dt>SQLITE_DB
1b7e0 43 4f 4e 46 49 47 5f 57 52 49 54 41 42 4c 45 5f  CONFIG_WRITABLE_
1b7f0 53 43 48 45 4d 41 3c 2f 64 74 3e 0a 2a 2a 20 3c  SCHEMA</dt>.** <
1b800 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 44 42  dd>The SQLITE_DB
1b810 43 4f 4e 46 49 47 5f 57 52 49 54 41 42 4c 45 5f  CONFIG_WRITABLE_
1b820 53 43 48 45 4d 41 20 6f 70 74 69 6f 6e 20 61 63  SCHEMA option ac
1b830 74 69 76 61 74 65 73 20 6f 72 20 64 65 61 63 74  tivates or deact
1b840 69 76 61 74 65 73 20 74 68 65 0a 2a 2a 20 22 77  ivates the.** "w
1b850 72 69 74 61 62 6c 65 5f 73 63 68 65 6d 61 22 20  ritable_schema" 
1b860 66 6c 61 67 2e 20 54 68 69 73 20 68 61 73 20 74  flag. This has t
1b870 68 65 20 73 61 6d 65 20 65 66 66 65 63 74 20 61  he same effect a
1b880 6e 64 20 69 73 20 6c 6f 67 69 63 61 6c 6c 79 20  nd is logically 
1b890 65 71 75 69 76 61 6c 65 6e 74 0a 2a 2a 20 74 6f  equivalent.** to
1b8a0 20 73 65 74 74 69 6e 67 20 5b 50 52 41 47 4d 41   setting [PRAGMA
1b8b0 20 77 72 69 74 61 62 6c 65 5f 73 63 68 65 6d 61   writable_schema
1b8c0 3d 4f 4e 5d 20 6f 72 20 5b 50 52 41 47 4d 41 20  =ON] or [PRAGMA 
1b8d0 77 72 69 74 61 62 6c 65 5f 73 63 68 65 6d 61 3d  writable_schema=
1b8e0 4f 46 46 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72  OFF]..** The fir
1b8f0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1b900 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 20 61  his setting is a
1b910 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
1b920 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
1b930 0a 2a 2a 20 74 68 65 20 77 72 69 74 61 62 6c 65  .** the writable
1b940 5f 73 63 68 65 6d 61 2c 20 70 6f 73 69 74 69 76  _schema, positiv
1b950 65 20 74 6f 20 65 6e 61 62 6c 65 20 77 72 69 74  e to enable writ
1b960 61 62 6c 65 5f 73 63 68 65 6d 61 2c 20 6f 72 20  able_schema, or 
1b970 6e 65 67 61 74 69 76 65 20 74 6f 0a 2a 2a 20 6c  negative to.** l
1b980 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
1b990 20 75 6e 63 68 61 6e 67 65 64 2e 20 54 68 65 20   unchanged. The 
1b9a0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1b9b0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
1b9c0 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69   an.** integer i
1b9d0 6e 74 6f 20 77 68 69 63 68 20 69 73 20 77 72 69  nto which is wri
1b9e0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
1b9f0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
1ba00 74 68 65 20 77 72 69 74 61 62 6c 65 5f 73 63 68  the writable_sch
1ba10 65 6d 61 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65  ema.** is enable
1ba20 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66 6f  d or disabled fo
1ba30 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
1ba40 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  l..** </dd>.**.*
1ba50 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  * [[SQLITE_DBCON
1ba60 46 49 47 5f 4c 45 47 41 43 59 5f 41 4c 54 45 52  FIG_LEGACY_ALTER
1ba70 5f 54 41 42 4c 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  _TABLE]].** <dt>
1ba80 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1ba90 4c 45 47 41 43 59 5f 41 4c 54 45 52 5f 54 41 42  LEGACY_ALTER_TAB
1baa0 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  LE</dt>.** <dd>T
1bab0 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
1bac0 49 47 5f 4c 45 47 41 43 59 5f 41 4c 54 45 52 5f  IG_LEGACY_ALTER_
1bad0 54 41 42 4c 45 20 6f 70 74 69 6f 6e 20 61 63 74  TABLE option act
1bae0 69 76 61 74 65 73 20 6f 72 20 64 65 61 63 74 69  ivates or deacti
1baf0 76 61 74 65 73 0a 2a 2a 20 74 68 65 20 6c 65 67  vates.** the leg
1bb00 61 63 79 20 62 65 68 61 76 69 6f 72 20 6f 66 20  acy behavior of 
1bb10 74 68 65 20 5b 41 4c 54 45 52 20 54 41 42 4c 45  the [ALTER TABLE
1bb20 20 52 45 4e 41 4d 45 5d 20 63 6f 6d 6d 61 6e 64   RENAME] command
1bb30 20 73 75 63 68 20 69 74 0a 2a 2a 20 62 65 68 61   such it.** beha
1bb40 76 65 73 20 61 73 20 69 74 20 64 69 64 20 70 72  ves as it did pr
1bb50 69 6f 72 20 74 6f 20 5b 76 65 72 73 69 6f 6e 20  ior to [version 
1bb60 33 2e 32 34 2e 30 5d 20 28 32 30 31 38 2d 30 36  3.24.0] (2018-06
1bb70 2d 30 34 29 2e 20 20 53 65 65 20 74 68 65 0a 2a  -04).  See the.*
1bb80 2a 20 22 43 6f 6d 70 61 74 69 62 69 6c 69 74 79  * "Compatibility
1bb90 20 4e 6f 74 69 63 65 22 20 6f 6e 20 74 68 65 20   Notice" on the 
1bba0 5b 41 4c 54 45 52 20 54 41 42 4c 45 20 52 45 4e  [ALTER TABLE REN
1bbb0 41 4d 45 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  AME documentatio
1bbc0 6e 5d 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  n] for.** additi
1bbd0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
1bbe0 2e 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63  . This feature c
1bbf0 61 6e 20 61 6c 73 6f 20 62 65 20 74 75 72 6e 65  an also be turne
1bc00 64 20 6f 6e 20 61 6e 64 20 6f 66 66 0a 2a 2a 20  d on and off.** 
1bc10 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d  using the [PRAGM
1bc20 41 20 6c 65 67 61 63 79 5f 61 6c 74 65 72 5f 74  A legacy_alter_t
1bc30 61 62 6c 65 5d 20 73 74 61 74 65 6d 65 6e 74 2e  able] statement.
1bc40 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
1bc50 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  [[SQLITE_DBCONFI
1bc60 47 5f 44 51 53 5f 44 4d 4c 5d 5d 0a 2a 2a 20 3c  G_DQS_DML]].** <
1bc70 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
1bc80 49 47 5f 44 51 53 5f 44 4d 4c 3c 2f 74 64 3e 0a  IG_DQS_DML</td>.
1bc90 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54  ** <dd>The SQLIT
1bca0 45 5f 44 42 43 4f 4e 46 49 47 5f 44 51 53 5f 44  E_DBCONFIG_DQS_D
1bcb0 4d 4c 20 6f 70 74 69 6f 6e 20 61 63 74 69 76 61  ML option activa
1bcc0 74 65 73 20 6f 72 20 64 65 61 63 74 69 76 61 74  tes or deactivat
1bcd0 65 73 0a 2a 2a 20 74 68 65 20 6c 65 67 61 63 79  es.** the legacy
1bce0 20 5b 64 6f 75 62 6c 65 2d 71 75 6f 74 65 64 20   [double-quoted 
1bcf0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 5d 20  string literal] 
1bd00 6d 69 73 66 65 61 74 75 72 65 20 66 6f 72 20 44  misfeature for D
1bd10 4d 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ML statement.** 
1bd20 6f 6e 6c 79 2c 20 74 68 61 74 20 69 73 20 44 45  only, that is DE
1bd30 4c 45 54 45 2c 20 49 4e 53 45 52 54 2c 20 53 45  LETE, INSERT, SE
1bd40 4c 45 43 54 2c 20 61 6e 64 20 55 50 44 41 54 45  LECT, and UPDATE
1bd50 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 54 68 65   statements. The
1bd60 0a 2a 2a 20 64 65 66 61 75 6c 74 20 76 61 6c 75  .** default valu
1bd70 65 20 6f 66 20 74 68 69 73 20 73 65 74 74 69 6e  e of this settin
1bd80 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 20  g is determined 
1bd90 62 79 20 74 68 65 20 5b 2d 44 53 51 4c 49 54 45  by the [-DSQLITE
1bda0 5f 44 51 53 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  _DQS].** compile
1bdb0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
1bdc0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
1bdd0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44  QLITE_DBCONFIG_D
1bde0 51 53 5f 44 44 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e  QS_DDL]].** <dt>
1bdf0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1be00 44 51 53 5f 44 44 4c 3c 2f 74 64 3e 0a 2a 2a 20  DQS_DDL</td>.** 
1be10 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 44  <dd>The SQLITE_D
1be20 42 43 4f 4e 46 49 47 5f 44 51 53 20 6f 70 74 69  BCONFIG_DQS opti
1be30 6f 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20  on activates or 
1be40 64 65 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74  deactivates.** t
1be50 68 65 20 6c 65 67 61 63 79 20 5b 64 6f 75 62 6c  he legacy [doubl
1be60 65 2d 71 75 6f 74 65 64 20 73 74 72 69 6e 67 20  e-quoted string 
1be70 6c 69 74 65 72 61 6c 5d 20 6d 69 73 66 65 61 74  literal] misfeat
1be80 75 72 65 20 66 6f 72 20 44 44 4c 20 73 74 61 74  ure for DDL stat
1be90 65 6d 65 6e 74 73 2c 0a 2a 2a 20 73 75 63 68 20  ements,.** such 
1bea0 61 73 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  as CREATE TABLE 
1beb0 61 6e 64 20 43 52 45 41 54 45 20 49 4e 44 45 58  and CREATE INDEX
1bec0 2e 20 54 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  . The.** default
1bed0 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 73   value of this s
1bee0 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d  etting is determ
1bef0 69 6e 65 64 20 62 79 20 74 68 65 20 5b 2d 44 53  ined by the [-DS
1bf00 51 4c 49 54 45 5f 44 51 53 5d 0a 2a 2a 20 63 6f  QLITE_DQS].** co
1bf10 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
1bf20 6e 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c  n..** </dd>.** <
1bf30 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
1bf40 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1bf50 4d 41 49 4e 44 42 4e 41 4d 45 20 20 20 20 20 20  MAINDBNAME      
1bf60 20 20 20 20 20 20 31 30 30 30 20 2f 2a 20 63 6f        1000 /* co
1bf70 6e 73 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65  nst char* */.#de
1bf80 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
1bf90 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
1bfa0 20 20 20 20 20 20 20 20 20 20 20 31 30 30 31 20             1001 
1bfb0 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74  /* void* int int
1bfc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1bfd0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
1bfe0 4c 45 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20  LE_FKEY         
1bff0 20 20 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e    1002 /* int in
1c000 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
1c010 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
1c020 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20  ABLE_TRIGGER    
1c030 20 20 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20      1003 /* int 
1c040 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
1c050 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1c060 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45  ENABLE_FTS3_TOKE
1c070 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e  NIZER 1004 /* in
1c080 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
1c090 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1c0a0 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58  G_ENABLE_LOAD_EX
1c0b0 54 45 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20  TENSION 1005 /* 
1c0c0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
1c0d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1c0e0 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43  FIG_NO_CKPT_ON_C
1c0f0 4c 4f 53 45 20 20 20 20 20 20 31 30 30 36 20 2f  LOSE      1006 /
1c100 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
1c110 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1c120 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53  ONFIG_ENABLE_QPS
1c130 47 20 20 20 20 20 20 20 20 20 20 20 31 30 30 37  G           1007
1c140 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
1c150 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1c160 42 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f  BCONFIG_TRIGGER_
1c170 45 51 50 20 20 20 20 20 20 20 20 20 20 20 31 30  EQP           10
1c180 30 38 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  08 /* int int* *
1c190 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c1a0 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f  _DBCONFIG_RESET_
1c1b0 44 41 54 41 42 41 53 45 20 20 20 20 20 20 20 20  DATABASE        
1c1c0 31 30 30 39 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1009 /* int int*
1c1d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c1e0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44 45 46 45  TE_DBCONFIG_DEFE
1c1f0 4e 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20  NSIVE           
1c200 20 20 31 30 31 30 20 2f 2a 20 69 6e 74 20 69 6e    1010 /* int in
1c210 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
1c220 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 57 52  LITE_DBCONFIG_WR
1c230 49 54 41 42 4c 45 5f 53 43 48 45 4d 41 20 20 20  ITABLE_SCHEMA   
1c240 20 20 20 20 31 30 31 31 20 2f 2a 20 69 6e 74 20      1011 /* int 
1c250 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
1c260 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1c270 4c 45 47 41 43 59 5f 41 4c 54 45 52 5f 54 41 42  LEGACY_ALTER_TAB
1c280 4c 45 20 20 20 20 31 30 31 32 20 2f 2a 20 69 6e  LE    1012 /* in
1c290 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
1c2a0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1c2b0 47 5f 44 51 53 5f 44 4d 4c 20 20 20 20 20 20 20  G_DQS_DML       
1c2c0 20 20 20 20 20 20 20 20 31 30 31 33 20 2f 2a 20          1013 /* 
1c2d0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
1c2e0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1c2f0 46 49 47 5f 44 51 53 5f 44 44 4c 20 20 20 20 20  FIG_DQS_DDL     
1c300 20 20 20 20 20 20 20 20 20 20 31 30 31 34 20 2f            1014 /
1c310 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
1c320 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1c330 4f 4e 46 49 47 5f 4d 41 58 20 20 20 20 20 20 20  ONFIG_MAX       
1c340 20 20 20 20 20 20 20 20 20 20 20 20 31 30 31 34              1014
1c350 20 2f 2a 20 4c 61 72 67 65 73 74 20 44 42 43 4f   /* Largest DBCO
1c360 4e 46 49 47 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  NFIG */../*.** C
1c370 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
1c380 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
1c390 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
1c3a0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1c3b0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
1c3c0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
1c3d0 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
1c3e0 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
1c3f0 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
1c400 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
1c410 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
1c420 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68  e of SQLite. ^Th
1c430 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
1c440 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64  t.** codes are d
1c450 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
1c460 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  lt for historica
1c470 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  l compatibility.
1c480 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1c490 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
1c4a0 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
1c4b0 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
1c4c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
1c4d0 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a  t Insert Rowid.*
1c4e0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1c4f0 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e  3.**.** ^Each en
1c500 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69  try in most SQLi
1c510 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 70  te tables (excep
1c520 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52  t for [WITHOUT R
1c530 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a  OWID] tables).**
1c540 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34   has a unique 64
1c550 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69  -bit signed.** i
1c560 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65  nteger key calle
1c570 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22  d the [ROWID | "
1c580 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f  rowid"]. ^The ro
1c590 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
1c5a0 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
1c5b0 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
1c5c0 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
1c5d0 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
1c5e0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
1c5f0 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
1c600 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
1c610 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
1c620 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a  ed columns. ^If.
1c630 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
1c640 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
1c650 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  e [INTEGER PRIMA
1c660 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61  RY KEY] then tha
1c670 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61  t column.** is a
1c680 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72  nother alias for
1c690 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a   the rowid..**.*
1c6a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  * ^The sqlite3_l
1c6b0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1c6c0 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 75 73  (D) interface us
1c6d0 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
1c6e0 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a 2a 20  e [rowid] of.** 
1c6f0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
1c700 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
1c710 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64  RT] into a rowid
1c720 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75   table or [virtu
1c730 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20  al table].** on 
1c740 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c750 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72 74 73 20  ion D. ^Inserts 
1c760 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f  into [WITHOUT RO
1c770 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20  WID] tables are 
1c780 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64 65 64 2e  not.** recorded.
1c790 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66   ^If no successf
1c7a0 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74  ul [INSERT]s int
1c7b0 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 68  o rowid tables h
1c7c0 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
1c7d0 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20 64 61 74  d .** on the dat
1c7e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c7f0 20 44 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33   D, then sqlite3
1c800 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1c810 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 0a 2a  id(D) returns .*
1c820 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 41 73  * zero..**.** As
1c830 20 77 65 6c 6c 20 61 73 20 62 65 69 6e 67 20 73   well as being s
1c840 65 74 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  et automatically
1c850 20 61 73 20 72 6f 77 73 20 61 72 65 20 69 6e 73   as rows are ins
1c860 65 72 74 65 64 20 69 6e 74 6f 20 64 61 74 61 62  erted into datab
1c870 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73 2c 20 74  ase.** tables, t
1c880 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1c890 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69  d by this functi
1c8a0 6f 6e 20 6d 61 79 20 62 65 20 73 65 74 20 65 78  on may be set ex
1c8b0 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a 2a 20 5b  plicitly by.** [
1c8c0 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74  sqlite3_set_last
1c8d0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
1c8e0 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69 72 74  .**.** Some virt
1c8f0 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
1c900 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 49 4e  entations may IN
1c910 53 45 52 54 20 72 6f 77 73 20 69 6e 74 6f 20 72  SERT rows into r
1c920 6f 77 69 64 20 74 61 62 6c 65 73 20 61 73 0a 2a  owid tables as.*
1c930 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d 6d 69 74  * part of commit
1c940 74 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69  ting a transacti
1c950 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66 6c 75 73  on (e.g. to flus
1c960 68 20 64 61 74 61 20 61 63 63 75 6d 75 6c 61 74  h data accumulat
1c970 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ed in memory.** 
1c980 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20 74 68 69  to disk). In thi
1c990 73 20 63 61 73 65 20 73 75 62 73 65 71 75 65 6e  s case subsequen
1c9a0 74 20 63 61 6c 6c 73 20 74 6f 20 74 68 69 73 20  t calls to this 
1c9b0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 20  function return 
1c9c0 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 61 73 73  the rowid.** ass
1c9d0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
1c9e0 73 65 20 69 6e 74 65 72 6e 61 6c 20 49 4e 53 45  se internal INSE
1c9f0 52 54 20 6f 70 65 72 61 74 69 6f 6e 73 2c 20 77  RT operations, w
1ca00 68 69 63 68 20 6c 65 61 64 73 20 74 6f 20 0a 2a  hich leads to .*
1ca10 2a 20 75 6e 69 6e 74 75 69 74 69 76 65 20 72 65  * unintuitive re
1ca20 73 75 6c 74 73 2e 20 56 69 72 74 75 61 6c 20 74  sults. Virtual t
1ca30 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
1ca40 69 6f 6e 73 20 74 68 61 74 20 64 6f 20 77 72 69  ions that do wri
1ca50 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a 2a 20 74  te to rowid.** t
1ca60 61 62 6c 65 73 20 69 6e 20 74 68 69 73 20 77 61  ables in this wa
1ca70 79 20 63 61 6e 20 61 76 6f 69 64 20 74 68 69 73  y can avoid this
1ca80 20 70 72 6f 62 6c 65 6d 20 62 79 20 72 65 73 74   problem by rest
1ca90 6f 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e  oring the origin
1caa0 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20 76 61 6c  al .** rowid val
1cab0 75 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ue using [sqlite
1cac0 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72  3_set_last_inser
1cad0 74 5f 72 6f 77 69 64 28 29 5d 20 62 65 66 6f 72  t_rowid()] befor
1cae0 65 20 72 65 74 75 72 6e 69 6e 67 20 0a 2a 2a 20  e returning .** 
1caf0 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68 65 20 75  control to the u
1cb00 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ser..**.** ^(If 
1cb10 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75  an [INSERT] occu
1cb20 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  rs within a trig
1cb30 67 65 72 20 74 68 65 6e 20 74 68 69 73 20 72 6f  ger then this ro
1cb40 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a 20 72  utine will .** r
1cb50 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64  eturn the [rowid
1cb60 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65  ] of the inserte
1cb70 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73  d row as long as
1cb80 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73 20   the trigger is 
1cb90 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f 6e 63  .** running. Onc
1cba0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72  e the trigger pr
1cbb0 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74 68 65 20  ogram ends, the 
1cbc0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a  value returned .
1cbd0 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ** by this routi
1cbe0 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68  ne reverts to wh
1cbf0 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65  at it was before
1cc00 20 74 68 65 20 74 72 69 67 67 65 72 20 77 61 73   the trigger was
1cc10 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20   fired.)^.**.** 
1cc20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61  ^An [INSERT] tha
1cc30 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
1cc40 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
1cc50 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
1cc60 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
1cc70 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e  SERT] and does n
1cc80 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
1cc90 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1cca0 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e  this.** routine.
1ccb0 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f    ^Thus INSERT O
1ccc0 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
1ccd0 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
1cce0 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
1ccf0 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
1cd00 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
1cd10 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
1cd20 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
1cd30 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
1cd40 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
1cd50 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20   fails.  ^(When 
1cd60 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
1cd70 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
1cd80 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
1cd90 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
1cda0 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
1cdb0 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
1cdc0 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
1cdd0 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
1cde0 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
1cdf0 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
1ce00 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
1ce10 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
1ce20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
1ce30 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
1ce40 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
1ce50 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a  nterface.)^.**.*
1ce60 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
1ce70 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
1ce80 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ine, an [INSERT]
1ce90 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
1cea0 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
1ceb0 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
1cec0 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
1ced0 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
1cee0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
1cef0 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20  s accessible to 
1cf00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76  SQL statements v
1cf10 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f  ia the.** [last_
1cf20 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53  insert_rowid() S
1cf30 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
1cf40 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
1cf50 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
1cf60 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d  s a new [INSERT]
1cf70 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
1cf80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1cf90 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
1cfa0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
1cfb0 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66  rt_rowid()].** f
1cfc0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
1cfd0 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
1cfe0 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
1cff0 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20  ert [rowid],.** 
1d000 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
1d010 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1d020 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1d030 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75  rowid()] is.** u
1d040 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
1d050 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
1d060 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
1d070 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61  or the new.** la
1d080 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
1d090 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  ]..*/.sqlite3_in
1d0a0 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  t64 sqlite3_last
1d0b0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
1d0c0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1d0d0 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 74 68  CAPI3REF: Set th
1d0e0 65 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  e Last Insert Ro
1d0f0 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d 45  wid value..** ME
1d100 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1d110 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1d120 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  set_last_insert_
1d130 72 6f 77 69 64 28 44 2c 20 52 29 20 6d 65 74 68  rowid(D, R) meth
1d140 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65 20 61 70  od allows the ap
1d150 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20  plication to.** 
1d160 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 72 65  set the value re
1d170 74 75 72 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  turned by callin
1d180 67 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  g sqlite3_last_i
1d190 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 74  nsert_rowid(D) t
1d1a0 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75 74 20  o R .** without 
1d1b0 69 6e 73 65 72 74 69 6e 67 20 61 20 72 6f 77 20  inserting a row 
1d1c0 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
1d1d0 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  e..*/.void sqlit
1d1e0 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65  e3_set_last_inse
1d1f0 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
1d200 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
1d210 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d220 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
1d230 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
1d240 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  fied.** METHOD: 
1d250 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1d260 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
1d270 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
1d280 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64  of rows modified
1d290 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a  , inserted or.**
1d2a0 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
1d2b0 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
1d2c0 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20  mpleted INSERT, 
1d2d0 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
1d2e0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e  .** statement on
1d2f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1d300 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69  nnection specifi
1d310 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70  ed by the only p
1d320 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78  arameter..** ^Ex
1d330 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65  ecuting any othe
1d340 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74  r type of SQL st
1d350 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
1d360 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75   modify the valu
1d370 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
1d380 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
1d390 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e  **.** ^Only chan
1d3a0 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c  ges made directl
1d3b0 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c  y by the INSERT,
1d3c0 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
1d3d0 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a  E statement are.
1d3e0 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20  ** considered - 
1d3f0 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  auxiliary change
1d400 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 52 45  s caused by [CRE
1d410 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
1d420 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f  iggers], .** [fo
1d430 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
1d440 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20  s] or [REPLACE] 
1d450 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
1d460 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f  ution are not co
1d470 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68  unted..** .** Ch
1d480 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
1d490 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65  that are interce
1d4a0 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53  pted by .** [INS
1d4b0 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20  TEAD OF trigger 
1d4c0 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  | INSTEAD OF tri
1d4d0 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63  ggers] are not c
1d4e0 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c  ounted. ^The val
1d4f0 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ue .** returned 
1d500 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  by sqlite3_chang
1d510 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79  es() immediately
1d520 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54   after an INSERT
1d530 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20  , UPDATE or .** 
1d540 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
1d550 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69   run on a view i
1d560 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f  s always zero. O
1d570 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65  nly changes made
1d580 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62   to real .** tab
1d590 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  les are counted.
1d5a0 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72  .**.** Things ar
1d5b0 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74  e more complicat
1d5c0 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 74 65  ed if the sqlite
1d5d0 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  3_changes() func
1d5e0 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75  tion is.** execu
1d5f0 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 69 67  ted while a trig
1d600 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72  ger program is r
1d610 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79  unning. This may
1d620 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a   happen if the.*
1d630 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74  * program uses t
1d640 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
1d650 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20  L function], or 
1d660 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61  if some other ca
1d670 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
1d680 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74  on invokes sqlit
1d690 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72  e3_changes() dir
1d6a0 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c  ectly. Essential
1d6b0 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a  ly:.** .** <ul>.
1d6c0 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f  **   <li> ^(Befo
1d6d0 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72  re entering a tr
1d6e0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68  igger program th
1d6f0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1d700 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71   by.**        sq
1d710 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
1d720 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65  function is save
1d730 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 72 69  d. After the tri
1d740 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a  gger program .**
1d750 20 20 20 20 20 20 20 20 68 61 73 20 66 69 6e 69          has fini
1d760 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e  shed, the origin
1d770 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73 74  al value is rest
1d780 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20  ored.)^.** .**  
1d790 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61   <li> ^(Within a
1d7a0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1d7b0 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50   each INSERT, UP
1d7c0 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20  DATE and DELETE 
1d7d0 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74 65  .**        state
1d7e0 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 76 61  ment sets the va
1d7f0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1d800 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1d810 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f  ) .**        upo
1d820 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20  n completion as 
1d830 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73  normal. Of cours
1d840 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77 69  e, this value wi
1d850 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a  ll not include .
1d860 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63 68  **        any ch
1d870 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20  anges performed 
1d880 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c  by sub-triggers,
1d890 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f   as the sqlite3_
1d8a0 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20  changes() .**   
1d8b0 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20       value will 
1d8c0 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 65 73  be saved and res
1d8d0 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 63 68  tored after each
1d8e0 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61 73   sub-trigger has
1d8f0 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e   run.)^.** </ul>
1d900 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65  .** .** ^This me
1d910 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 65 20  ans that if the 
1d920 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1d930 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c  nction (or simil
1d940 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62  ar) is used.** b
1d950 79 20 74 68 65 20 66 69 72 73 74 20 49 4e 53 45  y the first INSE
1d960 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
1d970 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
1d980 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c  ithin a trigger,
1d990 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20   it .** returns 
1d9a0 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 65 74  the value as set
1d9b0 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e   when the callin
1d9c0 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61  g statement bega
1d9d0 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  n executing..** 
1d9e0 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 20 62  ^If it is used b
1d9f0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20  y the second or 
1da00 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 68 20  subsequent such 
1da10 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
1da20 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70   a trigger .** p
1da30 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75  rogram, the valu
1da40 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65  e returned refle
1da50 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  cts the number o
1da60 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20  f rows modified 
1da70 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69  by the .** previ
1da80 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ous INSERT, UPDA
1da90 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
1daa0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
1dab0 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
1dac0 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
1dad0 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
1dae0 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
1daf0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
1db00 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
1db10 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
1db20 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
1db30 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
1db40 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75  returned.** is u
1db50 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
1db60 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
1db70 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1db80 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
1db90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
1dba0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
1dbb0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 3c 6c 69 3e  nterface.** <li>
1dbc0 20 74 68 65 20 5b 63 6f 75 6e 74 5f 63 68 61 6e   the [count_chan
1dbd0 67 65 73 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c  ges pragma].** <
1dbe0 6c 69 3e 20 74 68 65 20 5b 63 68 61 6e 67 65 73  li> the [changes
1dbf0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1dc00 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 64 61  .** <li> the [da
1dc10 74 61 5f 76 65 72 73 69 6f 6e 20 70 72 61 67 6d  ta_version pragm
1dc20 61 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69  a].** </ul>.*/.i
1dc30 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
1dc40 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
1dc50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1dc60 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
1dc70 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20  ows Modified.** 
1dc80 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1dc90 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1dca0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1dcb0 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
1dcc0 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20   rows inserted, 
1dcd0 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64  modified or.** d
1dce0 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49  eleted by all [I
1dcf0 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
1dd00 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
1dd10 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65  tements complete
1dd20 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64  d.** since the d
1dd30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1dd40 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69  on was opened, i
1dd50 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65  ncluding those e
1dd60 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61  xecuted as.** pa
1dd70 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72  rt of trigger pr
1dd80 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69  ograms. ^Executi
1dd90 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70  ng any other typ
1dda0 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  e of SQL stateme
1ddb0 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61  nt.** does not a
1ddc0 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20  ffect the value 
1ddd0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1dde0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1ddf0 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61  s()..** .** ^Cha
1de00 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72  nges made as par
1de10 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65  t of [foreign ke
1de20 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69  y actions] are i
1de30 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a  ncluded in the.*
1de40 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f  * count, but tho
1de50 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  se made as part 
1de60 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74  of REPLACE const
1de70 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
1de80 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68   are.** not. ^Ch
1de90 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
1dea0 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65  that are interce
1deb0 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20  pted by INSTEAD 
1dec0 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20  OF triggers .** 
1ded0 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
1dee0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
1def0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1df00 73 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  s(D)] interface 
1df10 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 74 68 65  only reports the
1df20 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 72 6f   number.** of ro
1df30 77 73 20 74 68 61 74 20 63 68 61 6e 67 65 64 20  ws that changed 
1df40 64 75 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65  due to SQL state
1df50 6d 65 6e 74 20 72 75 6e 20 61 67 61 69 6e 73 74  ment run against
1df60 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
1df70 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 79 20  nection D.  Any 
1df80 63 68 61 6e 67 65 73 20 62 79 20 6f 74 68 65 72  changes by other
1df90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1dfa0 74 69 6f 6e 73 20 61 72 65 20 69 67 6e 6f 72 65  tions are ignore
1dfb0 64 2e 0a 2a 2a 20 54 6f 20 64 65 74 65 63 74 20  d..** To detect 
1dfc0 63 68 61 6e 67 65 73 20 61 67 61 69 6e 73 74 20  changes against 
1dfd0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
1dfe0 66 72 6f 6d 20 6f 74 68 65 72 20 64 61 74 61 62  from other datab
1dff0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
1e000 6e 73 20 75 73 65 20 74 68 65 20 5b 50 52 41 47  ns use the [PRAG
1e010 4d 41 20 64 61 74 61 5f 76 65 72 73 69 6f 6e 5d  MA data_version]
1e020 20 63 6f 6d 6d 61 6e 64 20 6f 72 20 74 68 65 0a   command or the.
1e030 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
1e040 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 5d 20 5b  _DATA_VERSION] [
1e050 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 5d 2e 0a 2a  file control]..*
1e060 2a 20 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  * .** If a separ
1e070 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
1e080 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
1e090 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
1e0a0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
1e0b0 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
1e0c0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
1e0d0 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
1e0e0 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
1e0f0 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
1e100 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
1e110 6e 67 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ngful..**.** See
1e120 20 61 6c 73 6f 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a   also:.** <ul>.*
1e130 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 73 71 6c 69  * <li> the [sqli
1e140 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
1e150 6e 74 65 72 66 61 63 65 0a 2a 2a 20 3c 6c 69 3e  nterface.** <li>
1e160 20 74 68 65 20 5b 63 6f 75 6e 74 5f 63 68 61 6e   the [count_chan
1e170 67 65 73 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c  ges pragma].** <
1e180 6c 69 3e 20 74 68 65 20 5b 63 68 61 6e 67 65 73  li> the [changes
1e190 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1e1a0 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 64 61  .** <li> the [da
1e1b0 74 61 5f 76 65 72 73 69 6f 6e 20 70 72 61 67 6d  ta_version pragm
1e1c0 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b  a].** <li> the [
1e1d0 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41 54  SQLITE_FCNTL_DAT
1e1e0 41 5f 56 45 52 53 49 4f 4e 5d 20 5b 66 69 6c 65  A_VERSION] [file
1e1f0 20 63 6f 6e 74 72 6f 6c 5d 0a 2a 2a 20 3c 2f 75   control].** </u
1e200 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
1e210 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1e220 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1e230 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
1e240 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
1e250 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45  ning Query.** ME
1e260 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1e270 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
1e280 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
1e290 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
1e2a0 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
1e2b0 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
1e2c0 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
1e2d0 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
1e2e0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
1e2f0 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
1e300 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
1e310 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
1e320 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
1e330 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
1e340 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
1e350 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
1e360 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
1e370 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
1e380 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
1e390 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
1e3a0 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
1e3b0 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
1e3c0 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
1e3d0 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
1e3e0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
1e3f0 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
1e400 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
1e410 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
1e420 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
1e430 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
1e440 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1e450 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
1e460 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
1e470 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
1e480 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1e490 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
1e4a0 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
1e4b0 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
1e4c0 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
1e4d0 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
1e4e0 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
1e4f0 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
1e500 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
1e510 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
1e520 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
1e530 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
1e540 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
1e550 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
1e560 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
1e570 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
1e580 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
1e590 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
1e5a0 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
1e5b0 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
1e5c0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
1e5d0 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
1e5e0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
1e5f0 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
1e600 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
1e610 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
1e620 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
1e630 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
1e640 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
1e650 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
1e660 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
1e670 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
1e680 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
1e690 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
1e6a0 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
1e6b0 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
1e6c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e6d0 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
1e6e0 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
1e6f0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
1e700 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
1e710 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
1e720 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1e730 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
1e740 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
1e750 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
1e760 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
1e770 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
1e780 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
1e790 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
1e7a0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1e7b0 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
1e7c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1e7d0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1e7e0 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
1e7f0 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
1e800 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
1e810 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
1e820 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
1e830 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1e840 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
1e850 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1e860 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
1e870 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
1e880 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
1e890 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
1e8a0 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
1e8b0 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
1e8c0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1e8d0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1e8e0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
1e8f0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
1e900 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76  ll returns..*/.v
1e910 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
1e920 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
1e930 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e940 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
1e950 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
1e960 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
1e970 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1e980 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
1e990 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
1e9a0 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
1e9b0 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
1e9c0 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
1e9d0 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
1e9e0 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
1e9f0 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
1ea00 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
1ea10 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
1ea20 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
1ea30 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
1ea40 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
1ea50 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
1ea60 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
1ea70 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1ea80 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
1ea90 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
1eaa0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
1eab0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
1eac0 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
1ead0 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
1eae0 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
1eaf0 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
1eb00 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
1eb10 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
1eb20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
1eb30 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
1eb40 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
1eb50 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
1eb60 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
1eb70 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
1eb80 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
1eb90 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
1eba0 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
1ebb0 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
1ebc0 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
1ebd0 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
1ebe0 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
1ebf0 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
1ec00 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
1ec10 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
1ec20 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
1ec30 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
1ec40 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
1ec50 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
1ec60 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
1ec70 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1ec80 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
1ec90 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
1eca0 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
1ecb0 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
1ecc0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
1ecd0 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
1ece0 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
1ecf0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1ed00 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
1ed10 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
1ed20 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
1ed30 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
1ed40 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
1ed50 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
1ed60 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
1ed70 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
1ed80 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
1ed90 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
1eda0 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
1edb0 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
1edc0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
1edd0 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
1ede0 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
1edf0 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
1ee00 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
1ee10 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
1ee20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
1ee30 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
1ee40 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
1ee50 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
1ee60 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
1ee70 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
1ee80 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
1ee90 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1eea0 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
1eeb0 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
1eec0 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
1eed0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1eee0 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
1eef0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1ef00 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
1ef10 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
1ef20 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
1ef30 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
1ef40 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1ef50 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
1ef60 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
1ef70 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
1ef80 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1ef90 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
1efa0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
1efb0 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
1efc0 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
1efd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1efe0 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
1eff0 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
1f000 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
1f010 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73  * KEYWORDS: {bus
1f020 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
1f030 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65  ck} {busy handle
1f040 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
1f050 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
1f060 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1f070 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75  ndler(D,X,P) rou
1f080 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
1f090 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a  back function X.
1f0a0 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  ** that might be
1f0b0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
1f0c0 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
1f0d0 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
1f0e0 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
1f0f0 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  s a database tab
1f100 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  le associated wi
1f110 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  th.** [database 
1f120 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68  connection] D wh
1f130 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  en another threa
1f140 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
1f150 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f  has the table lo
1f160 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  cked..** The sql
1f170 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1f180 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  r() interface is
1f190 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1f1a0 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nt.** [sqlite3_b
1f1b0 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61  usy_timeout()] a
1f1c0 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  nd [PRAGMA busy_
1f1d0 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20  timeout]..**.** 
1f1e0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
1f1f0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
1f200 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
1f210 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
1f220 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
1f230 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
1f240 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
1f250 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
1f260 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
1f270 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
1f280 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
1f290 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
1f2a0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1f2b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1f2c0 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
1f2d0 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
1f2e0 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
1f2f0 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
1f300 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
1f310 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
1f320 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
1f330 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1f340 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
1f350 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
1f360 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
1f370 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
1f380 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1f390 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
1f3a0 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20  oked previously 
1f3b0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63  for the same loc
1f3c0 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
1f3d0 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
1f3e0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
1f3f0 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
1f400 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
1f410 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
1f420 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
1f430 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
1f440 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ] is returned.**
1f450 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1f460 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
1f470 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1f480 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
1f490 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
1f4a0 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  ** is made to ac
1f4b0 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
1f4c0 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  e and the cycle 
1f4d0 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
1f4e0 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
1f4f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
1f500 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
1f510 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
1f520 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
1f530 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
1f540 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
1f550 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
1f560 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
1f570 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
1f580 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
1f590 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
1f5a0 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
1f5b0 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
1f5c0 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74  TE_BUSY].** to t
1f5d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
1f5e0 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
1f5f0 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20  ng the .** busy 
1f600 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
1f610 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
1f620 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
1f630 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
1f640 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
1f650 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
1f660 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
1f670 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
1f680 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
1f690 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
1f6a0 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
1f6b0 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
1f6c0 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
1f6d0 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
1f6e0 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
1f6f0 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
1f700 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
1f710 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1f720 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
1f730 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
1f740 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
1f750 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
1f760 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1f770 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
1f780 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
1f790 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
1f7a0 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
1f7b0 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
1f7c0 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
1f7d0 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
1f7e0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1f7f0 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
1f800 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
1f810 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
1f820 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
1f830 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
1f840 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
1f850 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
1f860 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
1f870 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
1f880 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1f890 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
1f8a0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
1f8b0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1f8c0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1f8d0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
1f8e0 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
1f8f0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1f900 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
1f910 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
1f920 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
1f930 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1f940 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
1f950 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
1f960 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1f970 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72  timeout()].** or
1f980 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41   evaluating [PRA
1f990 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1f9a0 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20  =N] will change 
1f9b0 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  the.** busy hand
1f9c0 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65  ler and thus cle
1f9d0 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c  ar any previousl
1f9e0 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c  y set busy handl
1f9f0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
1fa00 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
1fa10 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
1fa20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
1fa30 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
1fa40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1fa50 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1fa60 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
1fa70 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a  In other words,.
1fa80 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1fa90 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ler is not reent
1faa0 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20  rant.  Any such 
1fab0 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
1fac0 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
1fad0 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
1fae0 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
1faf0 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
1fb00 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1fb10 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
1fb20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1fb30 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1fb40 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
1fb50 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1fb60 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
1fb70 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64  te3*,int(*)(void
1fb80 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a  *,int),void*);..
1fb90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1fba0 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
1fbb0 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ut.** METHOD: sq
1fbc0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1fbd0 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
1fbe0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1fbf0 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
1fc00 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
1fc10 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
1fc20 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
1fc30 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
1fc40 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54  e is locked.  ^T
1fc50 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
1fc60 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
1fc70 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
1fc80 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
1fc90 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1fca0 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
1fcb0 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65  umulated.  ^Afte
1fcc0 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  r at least "ms" 
1fcd0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
1fce0 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
1fcf0 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
1fd00 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
1fd10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1fd20 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
1fd30 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a  QLITE_BUSY]..**.
1fd40 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
1fd50 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
1fd60 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
1fd70 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
1fd80 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
1fd90 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
1fda0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
1fdb0 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1fdc0 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1fdd0 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
1fde0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1fdf0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
1fe00 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  t any given mome
1fe10 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
1fe20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
1fe30 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
1fe40 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
1fe50 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
1fe60 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
1fe70 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
1fe80 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
1fe90 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
1fea0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ed.)^.**.** See 
1feb0 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62  also:  [PRAGMA b
1fec0 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a  usy_timeout].*/.
1fed0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
1fee0 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
1fef0 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
1ff00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
1ff10 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
1ff20 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
1ff30 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  eries.** METHOD:
1ff40 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
1ff50 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20  his is a legacy 
1ff60 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69  interface that i
1ff70 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20  s preserved for 
1ff80 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1ff90 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20  ibility..** Use 
1ffa0 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
1ffb0 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65  e is not recomme
1ffc0 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69  nded..**.** Defi
1ffd0 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
1ffe0 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
1fff0 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
20000 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
20010 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
20020 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
20030 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
20040 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
20050 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
20060 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
20070 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
20080 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
20090 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
200a0 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
200b0 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
200c0 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
200d0 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
200e0 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
200f0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
20100 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
20110 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
20120 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
20130 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
20140 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
20150 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
20160 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
20170 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
20180 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
20190 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
201a0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
201b0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
201c0 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
201d0 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
201e0 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
201f0 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
20200 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
20210 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
20220 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
20230 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
20240 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
20250 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
20260 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
20270 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
20280 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
20290 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
202a0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
202b0 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
202c0 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
202d0 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
202e0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
202f0 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
20300 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
20310 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
20320 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
20330 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
20340 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
20350 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
20360 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
20370 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
20380 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
20390 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
203a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
203b0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
203c0 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
203d0 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
203e0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
203f0 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  le()]..**.** ^(A
20400 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
20410 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
20420 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
20430 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
20440 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
20450 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
20460 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
20470 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
20480 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
20490 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
204a0 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
204b0 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
204c0 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
204d0 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
204e0 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
204f0 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
20500 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
20510 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
20520 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
20530 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
20540 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
20550 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
20560 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
20570 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
20580 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
20590 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
205a0 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
205b0 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
205c0 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
205d0 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
205e0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
205f0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
20600 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
20610 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
20620 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
20630 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
20640 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
20650 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
20660 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
20670 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
20680 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
20690 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
206a0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
206b0 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
206c0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
206d0 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
206e0 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
206f0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
20700 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
20710 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
20720 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
20730 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
20740 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
20750 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
20760 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
20770 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
20780 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
20790 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
207a0 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
207b0 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
207c0 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  er and returns a
207d0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
207e0 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
207f0 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
20800 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
20810 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c  * After the appl
20820 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  ication has fini
20830 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65  shed with the re
20840 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65  sult from sqlite
20850 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a  3_get_table(),.*
20860 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74  * it must pass t
20870 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
20880 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
20890 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
208a0 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
208b0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
208c0 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
208d0 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
208e0 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
208f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
20900 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
20910 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
20920 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
20930 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
20940 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
20950 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
20960 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
20970 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
20980 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
20990 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
209a0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
209b0 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
209c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
209d0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
209e0 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
209f0 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
20a00 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
20a10 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
20a20 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
20a30 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
20a40 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
20a50 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
20a60 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
20a70 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
20a80 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
20a90 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
20aa0 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
20ab0 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
20ac0 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
20ad0 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
20ae0 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
20af0 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
20b00 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
20b10 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
20b20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
20b30 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
20b40 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
20b50 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
20b60 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
20b70 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
20b80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
20b90 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
20ba0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
20bb0 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
20bc0 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
20bd0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
20be0 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
20bf0 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
20c00 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
20c10 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
20c20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
20c30 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
20c40 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
20c50 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
20c60 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
20c70 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
20c80 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
20c90 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
20ca0 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
20cb0 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
20cc0 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
20cd0 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
20ce0 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
20cf0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
20d00 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
20d10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20d20 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
20d30 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
20d40 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
20d50 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
20d60 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
20d70 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
20d80 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
20d90 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
20da0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
20db0 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
20dc0 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d  nes understand m
20dd0 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f  ost of the commo
20de0 6e 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  n formatting opt
20df0 69 6f 6e 73 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  ions from.** the
20e00 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72   standard librar
20e10 79 20 70 72 69 6e 74 66 28 29 20 0a 2a 2a 20 70  y printf() .** p
20e20 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  lus some additio
20e30 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64  nal non-standard
20e40 20 66 6f 72 6d 61 74 73 20 28 5b 25 71 5d 2c 20   formats ([%q], 
20e50 5b 25 51 5d 2c 20 5b 25 77 5d 2c 20 61 6e 64 20  [%Q], [%w], and 
20e60 5b 25 7a 5d 29 2e 0a 2a 2a 20 53 65 65 20 74 68  [%z])..** See th
20e70 65 20 5b 62 75 69 6c 74 2d 69 6e 20 70 72 69 6e  e [built-in prin
20e80 74 66 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74  tf()] documentat
20e90 69 6f 6e 20 66 6f 72 20 64 65 74 61 69 6c 73 2e  ion for details.
20ea0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
20eb0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
20ec0 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e  d sqlite3_vmprin
20ed0 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72  tf() routines wr
20ee0 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73  ite their.** res
20ef0 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ults into memory
20f00 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
20f10 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
20f20 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
20f30 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
20f40 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
20f50 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
20f60 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
20f70 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e  ite3_free()].  ^
20f80 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
20f90 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
20fa0 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
20fb0 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d 20 69  e3_malloc64()] i
20fc0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
20fd0 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
20fe0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
20ff0 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
21000 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ng..**.** ^(The 
21010 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
21020 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
21030 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e  milar to "snprin
21040 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68  tf()" from.** th
21050 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
21060 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c  rary.  The resul
21070 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  t is written int
21080 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20  o the.** buffer 
21090 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20  supplied as the 
210a0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
210b0 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67   whose size is g
210c0 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66  iven by.** the f
210d0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
210e0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72  Note that the or
210f0 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  der of the.** fi
21100 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65  rst two paramete
21110 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66  rs is reversed f
21120 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29  rom snprintf().)
21130 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a  ^  This is an.**
21140 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69   historical acci
21150 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74  dent that cannot
21160 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75   be fixed withou
21170 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61  t breaking.** ba
21180 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
21190 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61  ility.  ^(Note a
211a0 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
211b0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
211c0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
211d0 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
211e0 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
211f0 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
21200 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
21210 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
21220 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64  buffer.)^  We ad
21230 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
21240 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
21250 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
21260 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
21270 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
21280 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
21290 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
212a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
212b0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
212c0 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
212d0 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
212e0 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ibility..**.** ^
212f0 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62  As long as the b
21300 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72  uffer size is gr
21310 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c  eater than zero,
21320 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
21330 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  f().** guarantee
21340 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65  s that the buffe
21350 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  r is always zero
21360 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
21370 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
21380 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65  meter "n" is the
21390 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74   total size of t
213a0 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75  he buffer, inclu
213b0 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a  ding space for.*
213c0 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  * the zero termi
213d0 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c  nator.  So the l
213e0 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68  ongest string th
213f0 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65  at can be comple
21400 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20  tely.** written 
21410 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72  will be n-1 char
21420 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  acters..**.** ^T
21430 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  he sqlite3_vsnpr
21440 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
21450 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73  s a varargs vers
21460 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
21470 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a  nprintf()..**.**
21480 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 62 75 69   See also:  [bui
21490 6c 74 2d 69 6e 20 70 72 69 6e 74 66 28 29 5d 2c  lt-in printf()],
214a0 20 5b 70 72 69 6e 74 66 28 29 20 53 51 4c 20 66   [printf() SQL f
214b0 75 6e 63 74 69 6f 6e 5d 0a 2a 2f 0a 63 68 61 72  unction].*/.char
214c0 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
214d0 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
214e0 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
214f0 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
21500 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
21510 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
21520 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
21530 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
21540 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
21550 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e  te3_vsnprintf(in
21560 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
21570 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a  ar*, va_list);..
21580 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21590 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
215a0 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
215b0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
215c0 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
215d0 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
215e0 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
215f0 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
21600 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
21610 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
21620 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
21630 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
21640 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
21650 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
21660 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
21670 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
21680 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
21690 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
216a0 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
216b0 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
216c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
216d0 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
216e0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
216f0 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
21700 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
21710 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
21720 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
21730 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
21740 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  r..** ^If sqlite
21750 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
21760 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
21770 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
21780 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
21790 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
217a0 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61  ter.  ^If the pa
217b0 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
217c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
217d0 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
217e0 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
217f0 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
21800 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
21810 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
21820 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
21830 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72  4(N) routine wor
21840 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20  ks just like.** 
21850 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
21860 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
21870 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36  is an unsigned 6
21880 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e  4-bit integer in
21890 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69  stead.** of a si
218a0 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65  gned 32-bit inte
218b0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ger..**.** ^Call
218c0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
218d0 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
218e0 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
218f0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
21900 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
21910 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
21920 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
21930 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
21940 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
21950 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  used.  ^The sqli
21960 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
21970 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
21980 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
21990 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
219a0 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
219b0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
219c0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
219d0 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
219e0 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
219f0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
21a00 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
21a10 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
21a20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
21a30 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
21a40 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
21a50 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
21a60 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
21a70 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
21a80 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
21a90 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
21aa0 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
21ab0 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
21ac0 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
21ad0 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
21ae0 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
21af0 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
21b00 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
21b10 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
21b20 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
21b30 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
21b40 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
21b50 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
21b60 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69  3_realloc(X,N) i
21b70 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
21b80 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a  s to resize a.**
21b90 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c   prior memory al
21ba0 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65  location X to be
21bb0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
21bc0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20  s..** ^If the X 
21bd0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
21be0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
21bf0 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
21c00 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
21c10 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
21c20 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
21c30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
21c40 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68  oc(N)..** ^If th
21c50 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e N parameter to
21c60 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
21c70 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72  (X,N) is zero or
21c80 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
21c90 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
21ca0 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
21cb0 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
21cc0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29   sqlite3_free(X)
21cd0 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65  ..** ^sqlite3_re
21ce0 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72  alloc(X,N) retur
21cf0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
21d00 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
21d10 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
21d20 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
21d30 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e  ze or NULL if in
21d40 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
21d50 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a  y is available..
21d60 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
21d70 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
21d80 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
21d90 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
21da0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
21db0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
21dc0 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
21dd0 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
21de0 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
21df0 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
21e00 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65  loc(X,N) and the
21e10 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
21e20 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  n is freed..** ^
21e30 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  If sqlite3_reall
21e40 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20  oc(X,N) returns 
21e50 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f  NULL and N is po
21e60 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  sitive, then the
21e70 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  .** prior alloca
21e80 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65  tion is not free
21e90 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
21ea0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
21eb0 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20  X,N) interfaces 
21ec0 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61  works the same a
21ed0 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61  s.** sqlite3_rea
21ee0 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74  lloc(X,N) except
21ef0 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d   that N is a 64-
21f00 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
21f10 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  eger instead.** 
21f20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e  of a 32-bit sign
21f30 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  ed integer..**.*
21f40 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d  * ^If X is a mem
21f50 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70  ory allocation p
21f60 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
21f70 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
21f80 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c  malloc(),.** sql
21f90 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c  ite3_malloc64(),
21fa0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
21fb0 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  (), or sqlite3_r
21fc0 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e  ealloc64(), then
21fd0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
21fe0 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(X) returns the
21ff0 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65   size of that me
22000 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
22010 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68  in bytes..** ^Th
22020 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
22030 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a   by sqlite3_msiz
22040 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61  e(X) might be la
22050 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75  rger than the nu
22060 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73  mber.** of bytes
22070 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20   requested when 
22080 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e  X was allocated.
22090 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c    ^If X is a NUL
220a0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a  L pointer then.*
220b0 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  * sqlite3_msize(
220c0 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  X) returns zero.
220d0 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f    If X points to
220e0 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20   something that 
220f0 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65  is not.** the be
22100 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72  ginning of memor
22110 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72  y allocation, or
22120 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f   if it points to
22130 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76   a formerly.** v
22140 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  alid memory allo
22150 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20  cation that has 
22160 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20  now been freed, 
22170 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
22180 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  r.** of sqlite3_
22190 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65  msize(X) is unde
221a0 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62  fined and possib
221b0 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
221c0 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65  * ^The memory re
221d0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
221e0 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69  3_malloc(), sqli
221f0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a  te3_realloc(),.*
22200 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
22210 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  64(), and sqlite
22220 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a  3_realloc64().**
22230 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
22240 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
22250 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
22260 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20  y, or to a.** 4 
22270 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66  byte boundary if
22280 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42   the [SQLITE_4_B
22290 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c  YTE_ALIGNED_MALL
222a0 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  OC] compile-time
222b0 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  .** option is us
222c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  ed..**.** In SQL
222d0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
222e0 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
222f0 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
22300 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
22310 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
22320 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
22330 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
22340 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
22350 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
22360 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
22370 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
22380 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
22390 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
223a0 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
223b0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
223c0 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
223d0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69   used..**.** Pri
223e0 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72  or to SQLite ver
223f0 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65  sion 3.7.10, the
22400 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
22410 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
22420 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ed.** the system
22430 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
22440 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
22450 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
22460 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
22470 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
22480 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
22490 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
224a0 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
224b0 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
224c0 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
224d0 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
224e0 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
224f0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
22500 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65  ors were detecte
22510 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77  d, but.** they w
22520 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  ere reported bac
22530 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
22540 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
22550 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
22560 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
22570 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  NOMEM]..**.** Th
22580 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
22590 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
225a0 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
225b0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
225c0 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
225d0 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
225e0 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
225f0 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
22600 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
22610 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
22620 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
22630 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
22640 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
22650 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
22660 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
22670 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
22680 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
22690 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
226a0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
226b0 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
226c0 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
226d0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
226e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
226f0 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  loc()]..*/.void 
22700 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
22710 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
22720 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c  te3_malloc64(sql
22730 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f  ite3_uint64);.vo
22740 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
22750 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
22760 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
22770 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20  ealloc64(void*, 
22780 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b  sqlite3_uint64);
22790 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
227a0 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74  ee(void*);.sqlit
227b0 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  e3_uint64 sqlite
227c0 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a  3_msize(void*);.
227d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
227e0 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
227f0 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a  r Statistics.**.
22800 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
22810 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
22820 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
22830 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
22840 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
22850 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
22860 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
22870 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
22880 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72  _realloc()].** r
22890 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66  outines, which f
228a0 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  orm the built-in
228b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
228c0 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a  on subsystem..**
228d0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
228e0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
228f0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
22900 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
22910 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  ytes.** of memor
22920 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73  y currently outs
22930 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65  tanding (malloce
22940 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
22950 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
22960 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
22970 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  ter()] routine r
22980 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d  eturns the maxim
22990 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b  um.** value of [
229a0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
229b0 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65  sed()] since the
229c0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
229d0 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73  .** was last res
229e0 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  et.  ^The values
229f0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
22a00 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
22a10 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
22a20 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
22a30 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
22a40 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
22a50 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65   added by SQLite
22a60 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e   in its implemen
22a70 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  tation of [sqlit
22a80 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  e3_malloc()],.**
22a90 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
22aa0 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
22ab0 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
22ac0 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
22ad0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
22ae0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
22af0 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a   may call..**.**
22b00 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67   ^The memory hig
22b10 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  h-water mark is 
22b20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72  reset to the cur
22b30 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  rent value of.**
22b40 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
22b50 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20  _used()] if and 
22b60 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61  only if the para
22b70 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
22b80 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
22b90 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
22ba0 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  .  ^The value re
22bb0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71  turned.** by [sq
22bc0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
22bd0 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68  hwater(1)] is th
22be0 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
22bf0 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68  k.** prior to th
22c00 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69  e reset..*/.sqli
22c10 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
22c20 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
22c30 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  id);.sqlite3_int
22c40 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
22c50 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
22c60 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
22c70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
22c80 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
22c90 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
22ca0 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
22cb0 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
22cc0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
22cd0 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
22ce0 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
22cf0 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
22d00 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
22d10 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
22d20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
22d30 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
22d40 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
22d50 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
22d60 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
22d70 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
22d80 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
22d90 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
22da0 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
22db0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
22dc0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
22dd0 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
22de0 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
22df0 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
22e00 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
22e10 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
22e20 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
22e30 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
22e40 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
22e50 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20  to buffer P..** 
22e60 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72  ^The P parameter
22e70 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70   can be a NULL p
22e80 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ointer..**.** ^I
22e90 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  f this routine h
22ea0 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76  as not been prev
22eb0 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72  iously called or
22ec0 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
22ed0 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c  .** call had N l
22ee0 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20  ess than one or 
22ef0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
22f00 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50  or P, then the P
22f10 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64  RNG is.** seeded
22f20 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
22f30 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
22f40 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
22f50 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65  method of.** the
22f60 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
22f70 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
22f80 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f  * ^If the previo
22f90 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
22fa0 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e  routine had an N
22fb0 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e   of 1 or more an
22fc0 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20  d a.** non-NULL 
22fd0 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64  P then the pseud
22fe0 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
22ff0 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
23000 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
23010 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
23020 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
23030 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
23040 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64   method..*/.void
23050 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
23060 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
23070 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
23080 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
23090 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
230a0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45   Callbacks.** ME
230b0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
230c0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 68   KEYWORDS: {auth
230d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 7d  orizer callback}
230e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
230f0 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
23100 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  n authorizer cal
23110 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72  lback with a par
23120 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
23130 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
23140 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68  , supplied in th
23150 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
23160 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72  ..** ^The author
23170 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
23180 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
23190 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
231a0 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
231b0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
231c0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
231d0 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
231e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
231f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
23200 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69  are_v3()], [sqli
23210 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
23220 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
23230 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61  re16_v2()],.** a
23240 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
23250 61 72 65 31 36 5f 76 33 28 29 5d 2e 20 20 5e 41  are16_v3()].  ^A
23260 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
23270 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
23280 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
23290 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
232a0 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
232b0 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
232c0 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
232d0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
232e0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
232f0 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
23300 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
23310 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75  llowed.  ^The au
23320 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
23330 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
23340 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
23350 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
23360 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
23370 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
23380 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
23390 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
233a0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
233b0 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
233c0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
233d0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
233e0 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
233f0 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
23400 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
23410 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
23420 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61  rror.  ^If the a
23430 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
23440 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
23450 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
23460 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
23470 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
23480 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
23490 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
234a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
234b0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
234c0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
234d0 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
234e0 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
234f0 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
23500 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
23510 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
23520 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
23530 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
23540 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
23550 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
23560 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63  ok.  ^When the c
23570 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
23580 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
23590 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
235a0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
235b0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
235c0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
235d0 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
235e0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
235f0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
23600 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
23610 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
23620 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  nied. .**.** ^Th
23630 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
23640 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
23650 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
23660 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
23670 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
23680 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
23690 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
236a0 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65   interface. ^The
236b0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
236c0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
236d0 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
236e0 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
236f0 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
23700 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
23710 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
23720 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
23730 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68  horized. ^The th
23740 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
23750 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
23760 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
23770 61 72 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20  are either NULL 
23780 70 6f 69 6e 74 65 72 73 20 6f 72 20 7a 65 72 6f  pointers or zero
23790 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
237a0 6e 67 73 0a 2a 2a 20 74 68 61 74 20 63 6f 6e 74  ngs.** that cont
237b0 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 64  ain additional d
237c0 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
237d0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
237e0 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41 70 70  thorized..** App
237f0 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 61  lications must a
23800 6c 77 61 79 73 20 62 65 20 70 72 65 70 61 72 65  lways be prepare
23810 64 20 74 6f 20 65 6e 63 6f 75 6e 74 65 72 20 61  d to encounter a
23820 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e   NULL pointer in
23830 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 74   any.** of the t
23840 68 69 72 64 20 74 68 72 6f 75 67 68 20 74 68 65  hird through the
23850 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
23860 73 20 6f 66 20 74 68 65 20 61 75 74 68 6f 72 69  s of the authori
23870 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e  zation callback.
23880 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
23890 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
238a0 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
238b0 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
238c0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
238d0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
238e0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
238f0 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
23900 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
23910 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
23920 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
23930 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
23940 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
23950 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
23960 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
23970 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
23980 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
23990 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
239a0 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
239b0 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
239c0 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
239d0 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
239e0 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
239f0 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20   of a table..** 
23a00 5e 57 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73  ^When a table is
23a10 20 72 65 66 65 72 65 6e 63 65 64 20 62 79 20 61   referenced by a
23a20 20 5b 53 45 4c 45 43 54 5d 20 62 75 74 20 6e 6f   [SELECT] but no
23a30 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61   column values a
23a40 72 65 0a 2a 2a 20 65 78 74 72 61 63 74 65 64 20  re.** extracted 
23a50 66 72 6f 6d 20 74 68 61 74 20 74 61 62 6c 65 20  from that table 
23a60 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 69 6e 20  (for example in 
23a70 61 20 71 75 65 72 79 20 6c 69 6b 65 0a 2a 2a 20  a query like.** 
23a80 22 53 45 4c 45 43 54 20 63 6f 75 6e 74 28 2a 29  "SELECT count(*)
23a90 20 46 52 4f 4d 20 74 61 62 22 29 20 74 68 65 6e   FROM tab") then
23aa0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 52 45 41   the [SQLITE_REA
23ab0 44 5d 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  D] authorizer ca
23ac0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 69 6e 76  llback.** is inv
23ad0 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 74 68  oked once for th
23ae0 61 74 20 74 61 62 6c 65 20 77 69 74 68 20 61 20  at table with a 
23af0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20 74 68 61 74  column name that
23b00 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
23b10 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
23b20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
23b30 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61  SQLITE_DELETE] a
23b40 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
23b50 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
23b60 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
23b70 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65  the [DELETE] ope
23b80 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20  ration proceeds 
23b90 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e  but the.** [trun
23ba0 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f  cate optimizatio
23bb0 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61  n] is disabled a
23bc0 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20  nd all rows are 
23bd0 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75  deleted individu
23be0 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  ally..**.** An a
23bf0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65  uthorizer is use
23c00 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
23c10 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
23c20 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ing].** SQL stat
23c30 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75  ements from an u
23c40 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c  ntrusted source,
23c50 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20   to ensure that 
23c60 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
23c70 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79  ts.** do not try
23c80 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20   to access data 
23c90 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c  they are not all
23ca0 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20  owed to see, or 
23cb0 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
23cc0 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75  .** try to execu
23cd0 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61  te malicious sta
23ce0 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d  tements that dam
23cf0 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  age the database
23d00 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
23d10 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
23d20 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73  n may allow a us
23d30 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69  er to enter arbi
23d40 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65  trary.** SQL que
23d50 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74  ries for evaluat
23d60 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73  ion by a databas
23d70 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c  e.  But the appl
23d80 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20  ication does.** 
23d90 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65  not want the use
23da0 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20  r to be able to 
23db0 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63  make arbitrary c
23dc0 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a  hanges to the.**
23dd0 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61   database.  An a
23de0 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20  uthorizer could 
23df0 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70  then be put in p
23e00 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a  lace while the.*
23e10 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  * user-entered S
23e20 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c  QL is being [sql
23e30 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
23e40 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a  repared] that.**
23e50 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79   disallows every
23e60 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45  thing except [SE
23e70 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73  LECT] statements
23e80 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ..**.** Applicat
23e90 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74  ions that need t
23ea0 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72  o process SQL fr
23eb0 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  om untrusted sou
23ec0 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c  rces.** might al
23ed0 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65  so consider lowe
23ee0 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69  ring resource li
23ef0 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69  mits using [sqli
23f00 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
23f10 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74  and limiting dat
23f20 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67  abase size using
23f30 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63   the [max_page_c
23f40 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a  ount] [PRAGMA].*
23f50 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  * in addition to
23f60 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72   using an author
23f70 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  izer..**.** ^(On
23f80 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68  ly a single auth
23f90 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e  orizer can be in
23fa0 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61   place on a data
23fb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
23fc0 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45  ** at a time.  E
23fd0 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
23fe0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
23ff0 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  er overrides the
24000 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c  .** previous cal
24010 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74  l.)^  ^Disable t
24020 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79  he authorizer by
24030 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55   installing a NU
24040 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  LL callback..** 
24050 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69  The authorizer i
24060 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
24070 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fault..**.** The
24080 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
24090 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
240a0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
240b0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
240c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
240d0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
240e0 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ed the authorize
240f0 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e  r callback..** N
24100 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
24110 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
24120 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
24130 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
24140 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
24150 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
24160 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
24170 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
24180 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
24190 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74  .** ^When [sqlit
241a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
241b0 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70   is used to prep
241c0 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  are a statement,
241d0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
241e0 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72  t might be re-pr
241f0 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73  epared during [s
24200 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64  qlite3_step()] d
24210 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65  ue to a .** sche
24220 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63  ma change.  Henc
24230 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  e, the applicati
24240 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65  on should ensure
24250 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72   that the.** cor
24260 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20  rect authorizer 
24270 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73  callback remains
24280 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67   in place during
24290 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
242a0 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f  ep()]..**.** ^No
242b0 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68  te that the auth
242c0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
242d0 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20  is invoked only 
242e0 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  during.** [sqlit
242f0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
24300 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20   its variants.  
24310 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73  Authorization is
24320 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65   not.** performe
24330 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65  d during stateme
24340 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e  nt evaluation in
24350 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
24360 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20  ], unless.** as 
24370 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72  stated in the pr
24380 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
24390 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
243a0 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69   invokes.** sqli
243b0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
243c0 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20   to reprepare a 
243d0 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
243e0 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  a schema change.
243f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
24400 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
24410 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
24420 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
24430 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
24440 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
24450 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
24460 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
24470 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
24480 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
24490 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
244a0 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
244b0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
244c0 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
244d0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  zer callback fun
244e0 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72  ction] must.** r
244f0 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51  eturn either [SQ
24500 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20  LITE_OK] or one 
24510 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e  of these two con
24520 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a  stants in order.
24530 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c  ** to signal SQL
24540 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e  ite whether or n
24550 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  ot the action is
24560 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65   permitted.  See
24570 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
24580 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
24590 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63  | authorizer doc
245a0 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
245b0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
245c0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
245d0 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54   Note that SQLIT
245e0 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f  E_IGNORE is also
245f0 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66   used as a [conf
24600 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  lict resolution 
24610 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65  mode].** returne
24620 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  d from the [sqli
24630 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66  te3_vtab_on_conf
24640 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63  lict()] interfac
24650 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
24660 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
24670 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
24680 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
24690 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
246a0 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
246b0 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
246c0 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
246d0 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
246e0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
246f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
24700 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
24710 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
24720 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
24730 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
24740 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
24750 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
24760 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
24770 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
24780 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
24790 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
247a0 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
247b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
247c0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
247d0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
247e0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
247f0 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
24800 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
24810 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
24820 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
24830 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
24840 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
24850 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
24860 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
24870 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
24880 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
24890 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
248a0 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
248b0 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
248c0 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
248d0 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
248e0 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
248f0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
24900 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
24910 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
24920 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
24930 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
24940 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
24950 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
24960 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d   ^(The 5th param
24970 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
24980 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
24990 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
249a0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
249b0 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
249c0 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
249d0 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20  icable.)^  ^The 
249e0 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
249f0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
24a00 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
24a10 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
24a20 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
24a30 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
24a40 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
24a50 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
24a60 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
24a70 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
24a80 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
24a90 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
24aa0 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
24ab0 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
24ac0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
24ad0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
24ae0 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
24af0 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
24b00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24b10 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
24b20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
24b30 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
24b40 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
24b50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
24b60 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
24b70 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
24b80 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
24b90 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
24ba0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
24bb0 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
24bc0 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
24bd0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
24be0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
24bf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
24c00 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
24c10 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
24c20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
24c30 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
24c40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
24c50 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
24c60 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
24c70 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
24c80 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
24c90 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
24ca0 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
24cb0 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
24cc0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
24cd0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
24ce0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
24cf0 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
24d00 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
24d10 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
24d20 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
24d30 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
24d40 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
24d50 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
24d60 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
24d70 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
24d80 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
24d90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
24da0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
24db0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
24dc0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
24dd0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
24de0 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
24df0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
24e00 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
24e10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
24e20 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
24e30 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
24e40 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
24e50 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
24e60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
24e70 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
24e80 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
24e90 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
24ea0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
24eb0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
24ec0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
24ed0 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
24ee0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
24ef0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
24f00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24f10 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
24f20 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
24f30 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
24f40 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
24f50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24f60 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
24f70 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
24f80 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
24f90 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
24fa0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24fb0 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
24fc0 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
24fd0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
24fe0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
24ff0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25000 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
25010 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
25020 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
25030 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
25040 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
25050 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
25060 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
25070 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
25080 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
25090 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
250a0 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
250b0 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
250c0 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
250d0 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
250e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
250f0 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
25100 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
25110 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
25120 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
25130 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
25140 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
25150 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
25160 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
25170 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
25180 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
25190 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
251a0 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  22   /* Operatio
251b0 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  n       NULL    
251c0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
251d0 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
251e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
251f0 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
25200 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
25210 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
25220 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
25230 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
25240 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
25250 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
25260 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
25270 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
25280 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
25290 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
252a0 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
252b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
252c0 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
252d0 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
252e0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
252f0 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
25300 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
25310 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
25320 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
25330 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
25340 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
25350 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
25360 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
25370 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
25380 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
25390 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
253a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
253b0 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
253c0 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
253d0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
253e0 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
253f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
25400 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
25410 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
25420 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
25430 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
25440 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
25450 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
25460 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e         31   /* N
25470 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46  ULL            F
25480 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a  unction Name   *
25490 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
254a0 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20  _SAVEPOINT      
254b0 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70        32   /* Op
254c0 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61  eration       Sa
254d0 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f  vepoint Name  */
254e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
254f0 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
25500 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
25510 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23  longer used */.#
25520 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
25530 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20  CURSIVE         
25540 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20     33   /* NULL 
25550 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
25560 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f             */../
25570 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
25580 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69  racing And Profi
25590 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ling Functions.*
255a0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
255b0 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  3.**.** These ro
255c0 75 74 69 6e 65 73 20 61 72 65 20 64 65 70 72 65  utines are depre
255d0 63 61 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b  cated. Use the [
255e0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
255f0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
25600 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
25610 72 6f 75 74 69 6e 65 73 20 64 65 73 63 72 69 62  routines describ
25620 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54  ed here..**.** T
25630 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
25640 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
25650 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
25660 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
25670 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
25680 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
25690 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
256a0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
256b0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
256c0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
256d0 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
256e0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
256f0 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
25700 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
25710 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
25720 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
25730 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
25740 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
25750 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
25760 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
25770 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
25780 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
25790 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
257a0 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
257b0 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
257c0 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
257d0 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
257e0 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
257f0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
25800 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
25810 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
25820 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
25830 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
25840 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
25850 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
25860 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
25870 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
25880 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
25890 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d  E_TRACE_SIZE_LIM
258a0 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  IT] compile-time
258b0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
258c0 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20  sed to limit.** 
258d0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62  the length of [b
258e0 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20  ound parameter] 
258f0 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65  expansion in the
25900 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74   output of sqlit
25910 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a  e3_trace()..**.*
25920 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
25930 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
25940 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
25950 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f  rofile() is invo
25960 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53  ked.** as each S
25970 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  QL statement fin
25980 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f  ishes.  ^The pro
25990 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f  file callback co
259a0 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72  ntains.** the or
259b0 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
259c0 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74   text and an est
259d0 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c  imate of wall-cl
259e0 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68  ock time.** of h
259f0 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
25a00 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
25a10 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  un.  ^The profil
25a20 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69  e callback.** ti
25a30 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f  me is in units o
25a40 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68  f nanoseconds, h
25a50 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65  owever the curre
25a60 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
25a70 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70  n.** is only cap
25a80 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63  able of millisec
25a90 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73  ond resolution s
25aa0 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20  o the six least 
25ab0 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64  significant.** d
25ac0 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d  igits in the tim
25ad0 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73  e are meaningles
25ae0 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  s.  Future versi
25af0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ons of SQLite.**
25b00 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67   might provide g
25b10 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f  reater resolutio
25b20 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65  n on the profile
25b30 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 6e 76  r callback.  Inv
25b40 6f 6b 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20  oking.** either 
25b50 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
25b60 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 72  ] or [sqlite3_tr
25b70 61 63 65 5f 76 32 28 29 5d 20 77 69 6c 6c 20 63  ace_v2()] will c
25b80 61 6e 63 65 6c 20 74 68 65 0a 2a 2a 20 70 72 6f  ancel the.** pro
25b90 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  file callback..*
25ba0 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  /.SQLITE_DEPRECA
25bb0 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TED void *sqlite
25bc0 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a  3_trace(sqlite3*
25bd0 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 61 63  ,.   void(*xTrac
25be0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
25bf0 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53  har*), void*);.S
25c00 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
25c10 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70   void *sqlite3_p
25c20 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
25c30 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
25c40 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
25c50 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
25c60 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
25c70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25c80 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20  SQL Trace Event 
25c90 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
25ca0 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a  S: SQLITE_TRACE.
25cb0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
25cc0 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63  tants identify c
25cd0 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73  lasses of events
25ce0 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e   that can be mon
25cf0 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20  itored.** using 
25d00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61  the [sqlite3_tra
25d10 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67  ce_v2()] tracing
25d20 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 4d 20 61   logic.  The M a
25d30 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73  rgument.** to [s
25d40 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
25d50 44 2c 4d 2c 58 2c 50 29 5d 20 69 73 20 61 6e 20  D,M,X,P)] is an 
25d60 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f  OR-ed combinatio
25d70 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  n of one or more
25d80 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
25d90 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20  wing constants. 
25da0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
25db0 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63  ment to the trac
25dc0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  e callback.** is
25dd0 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
25de0 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e  owing constants.
25df0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69  .**.** New traci
25e00 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79  ng constants may
25e10 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
25e20 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  ure releases..**
25e30 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c  .** ^A trace cal
25e40 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20 61  lback has four a
25e50 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62  rguments: xCallb
25e60 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a  ack(T,C,P,X)..**
25e70 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74   ^The T argument
25e80 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 69   is one of the i
25e90 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f 64 65  nteger type code
25ea0 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65  s above..** ^The
25eb0 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   C argument is a
25ec0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
25ed0 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61 73  text pointer pas
25ee0 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a  sed in as the.**
25ef0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
25f00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   to [sqlite3_tra
25f10 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65  ce_v2()]..** The
25f20 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e   P and X argumen
25f30 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20  ts are pointers 
25f40 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64  whose meanings d
25f50 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a  epend on T..**.*
25f60 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
25f70 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20  TE_TRACE_STMT]] 
25f80 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45  <dt>SQLITE_TRACE
25f90 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _STMT</dt>.** <d
25fa0 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41  d>^An SQLITE_TRA
25fb0 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b  CE_STMT callback
25fc0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
25fd0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
25fe0 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62  ement.** first b
25ff0 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e  egins running an
26000 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f 74  d possibly at ot
26010 68 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e 67  her times during
26020 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f   the.** executio
26030 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65  n of the prepare
26040 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75 63  d statement, suc
26050 68 20 61 73 20 61 74 20 74 68 65 20 73 74 61 72  h as at the star
26060 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72 69  t of each.** tri
26070 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e  gger subprogram.
26080 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
26090 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
260a0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
260b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54  d statement]. ^T
260c0 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73  he X argument is
260d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
260e0 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20  string which.** 
260f0 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64 65  is the unexpande
26100 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74 68  d SQL text of th
26110 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
26120 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20 63  ment or an SQL c
26130 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20  omment .** that 
26140 69 6e 64 69 63 61 74 65 73 20 74 68 65 20 69 6e  indicates the in
26150 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74 72  vocation of a tr
26160 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61 6c  igger.  ^The cal
26170 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74  lback can comput
26180 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 65  e.** the same te
26190 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  xt that would ha
261a0 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ve been returned
261b0 20 62 79 20 74 68 65 20 6c 65 67 61 63 79 20 5b   by the legacy [
261c0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d  sqlite3_trace()]
261d0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62 79  .** interface by
261e0 20 75 73 69 6e 67 20 74 68 65 20 58 20 61 72 67   using the X arg
261f0 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65 67  ument when X beg
26200 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61 6e  ins with "--" an
26210 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73  d invoking.** [s
26220 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
26230 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69 73  sql(P)] otherwis
26240 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  e..**.** [[SQLIT
26250 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d  E_TRACE_PROFILE]
26260 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
26270 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a  CE_PROFILE</dt>.
26280 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54  ** <dd>^An SQLIT
26290 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20  E_TRACE_PROFILE 
262a0 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64 65  callback provide
262b0 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20  s approximately 
262c0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f  the same.** info
262d0 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70 72  rmation as is pr
262e0 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 5b 73  ovided by the [s
262f0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
26300 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e  ] callback..** ^
26310 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
26320 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
26330 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
26340 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a  tement] and the.
26350 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70 6f  ** X argument po
26360 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69 74  ints to a 64-bit
26370 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
26380 73 20 74 68 65 20 65 73 74 69 6d 61 74 65 64 20  s the estimated 
26390 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  of.** the number
263a0 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74   of nanosecond t
263b0 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64  hat the prepared
263c0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
263d0 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20  to run..** ^The 
263e0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f  SQLITE_TRACE_PRO
263f0 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69 73  FILE callback is
26400 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
26410 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  e statement fini
26420 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  shes..**.** [[SQ
26430 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d  LITE_TRACE_ROW]]
26440 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
26450 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  E_ROW</dt>.** <d
26460 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41  d>^An SQLITE_TRA
26470 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20  CE_ROW callback 
26480 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  is invoked whene
26490 76 65 72 20 61 20 70 72 65 70 61 72 65 64 0a 2a  ver a prepared.*
264a0 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e 65  * statement gene
264b0 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20 72  rates a single r
264c0 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a  ow of result.  .
264d0 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  ** ^The P argume
264e0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
264f0 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
26500 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
26510 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e  the.** X argumen
26520 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a  t is unused..**.
26530 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43  ** [[SQLITE_TRAC
26540 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51  E_CLOSE]] <dt>SQ
26550 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45  LITE_TRACE_CLOSE
26560 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e  </dt>.** <dd>^An
26570 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c   SQLITE_TRACE_CL
26580 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  OSE callback is 
26590 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 64  invoked when a d
265a0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
265b0 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a  ction closes..**
265c0 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
265d0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
265e0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
265f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63  onnection] objec
26600 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20 61  t.** and the X a
26610 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65  rgument is unuse
26620 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  d..** </dl>.*/.#
26630 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
26640 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20 30  ACE_STMT       0
26650 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  x01.#define SQLI
26660 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
26670 20 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65      0x02.#define
26680 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f   SQLITE_TRACE_RO
26690 57 20 20 20 20 20 20 20 20 30 78 30 34 0a 23 64  W        0x04.#d
266a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
266b0 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30 78  CE_CLOSE      0x
266c0 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  08../*.** CAPI3R
266d0 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48 6f  EF: SQL Trace Ho
266e0 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ok.** METHOD: sq
266f0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
26700 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
26710 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72  2(D,M,X,P) inter
26720 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
26730 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a   trace callback.
26740 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61 67  ** function X ag
26750 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65 20  ainst [database 
26760 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75  connection] D, u
26770 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d 61  sing property ma
26780 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74  sk M.** and cont
26790 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20 20  ext pointer P.  
267a0 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62 61  ^If the X callba
267b0 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72  ck is.** NULL or
267c0 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20 69   if the M mask i
267d0 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 61  s zero, then tra
267e0 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64  cing is disabled
267f0 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75  .  The.** M argu
26800 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
26810 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65 64  he bitwise OR-ed
26820 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
26830 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  ** zero or more 
26840 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20 63  [SQLITE_TRACE] c
26850 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  onstants..**.** 
26860 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65 69  ^Each call to ei
26870 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72 61  ther sqlite3_tra
26880 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  ce() or sqlite3_
26890 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72 72  trace_v2() overr
268a0 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c  ides .** (cancel
268b0 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c  s) any prior cal
268c0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72  ls to sqlite3_tr
268d0 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ace() or sqlite3
268e0 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a  _trace_v2()..**.
268f0 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62 61  ** ^The X callba
26900 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  ck is invoked wh
26910 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74 68  enever any of th
26920 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69 66  e events identif
26930 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20  ied by .** mask 
26940 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20 69  M occur.  ^The i
26950 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20 76 61  nteger return va
26960 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61 6c  lue from the cal
26970 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e 74  lback is current
26980 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74  ly.** ignored, t
26990 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20 63  hough this may c
269a0 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
269b0 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c 62  releases.  Callb
269c0 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ack.** implement
269d0 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65  ations should re
269e0 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73  turn zero to ens
269f0 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70 61  ure future compa
26a00 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
26a10 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ^A trace callbac
26a20 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
26a30 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73  h four arguments
26a40 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50  : callback(T,C,P
26a50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61  ,X)..** ^The T a
26a60 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
26a70 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 52  f the [SQLITE_TR
26a80 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74  ACE].** constant
26a90 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  s to indicate wh
26aa0 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77  y the callback w
26ab0 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e  as invoked..** ^
26ac0 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69  The C argument i
26ad0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
26ae0 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 2e  context pointer.
26af0 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20  .** The P and X 
26b00 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f  arguments are po
26b10 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61  inters whose mea
26b20 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20  nings depend on 
26b30 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  T..**.** The sql
26b40 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20  ite3_trace_v2() 
26b50 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74  interface is int
26b60 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63 65  ended to replace
26b70 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
26b80 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
26b90 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64 20  e3_trace()] and 
26ba0 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  [sqlite3_profile
26bb0 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68 69  ()], both of whi
26bc0 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65 63  ch.** are deprec
26bd0 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ated..*/.int sql
26be0 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a 20  ite3_trace_v2(. 
26bf0 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73   sqlite3*,.  uns
26c00 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69  igned uMask,.  i
26c10 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75  nt(*xCallback)(u
26c20 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f  nsigned,void*,vo
26c30 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f  id*,void*),.  vo
26c40 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a  id *pCtx.);../*.
26c50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
26c60 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
26c70 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  backs.** METHOD:
26c80 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
26c90 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  The sqlite3_prog
26ca0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e  ress_handler(D,N
26cb0 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20  ,X,P) interface 
26cc0 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
26cd0 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
26ce0 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  X to be invoked 
26cf0 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
26d00 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
26d10 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
26d20 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
26d30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
26d40 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  and [sqlite3_get
26d50 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a  _table()] for.**
26d60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
26d70 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d  tion D.  An exam
26d80 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
26d90 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
26da0 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
26db0 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
26dc0 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
26dd0 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  ** ^The paramete
26de0 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68  r P is passed th
26df0 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c  rough as the onl
26e00 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  y parameter to t
26e10 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  he .** callback 
26e20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68  function X.  ^Th
26e30 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73  e parameter N is
26e40 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65   the approximate
26e50 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b   number of .** [
26e60 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
26e70 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68  instructions] th
26e80 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  at are evaluated
26e90 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73   between success
26ea0 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ive.** invocatio
26eb0 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61  ns of the callba
26ec0 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20  ck X.  ^If N is 
26ed0 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68  less than one th
26ee0 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a  en the progress.
26ef0 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69  ** handler is di
26f00 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  sabled..**.** ^O
26f10 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f  nly a single pro
26f20 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61  gress handler ma
26f30 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20  y be defined at 
26f40 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20  one time per.** 
26f50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
26f60 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61  tion]; setting a
26f70 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61   new progress ha
26f80 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68  ndler cancels th
26f90 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e  e.** old one.  ^
26fa0 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65  Setting paramete
26fb0 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61  r X to NULL disa
26fc0 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73  bles the progres
26fd0 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54  s handler..** ^T
26fe0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
26ff0 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61  ler is also disa
27000 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20  bled by setting 
27010 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73  N to a value les
27020 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a  s.** than 1..**.
27030 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72  ** ^If the progr
27040 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
27050 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
27060 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
27070 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
27080 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
27090 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
270a0 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
270b0 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
270c0 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69   GUI progress di
270d0 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
270e0 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
270f0 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  dler callback mu
27100 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
27110 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
27120 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
27130 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
27140 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
27150 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
27160 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
27170 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
27180 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
27190 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
271a0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
271b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
271c0 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
271d0 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
271e0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
271f0 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73  ph..**.*/.void s
27200 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
27210 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
27220 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
27230 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
27240 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
27250 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
27260 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
27270 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a  .** CONSTRUCTOR:
27280 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
27290 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
272a0 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
272b0 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73  tabase file as s
272c0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
272d0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
272e0 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
272f0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
27300 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
27310 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
27320 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
27330 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
27340 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
27350 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
27360 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
27370 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
27380 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
27390 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
273a0 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
273b0 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
273c0 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
273d0 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
273e0 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
273f0 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
27400 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
27410 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
27420 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
27430 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
27440 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
27450 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
27460 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
27470 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
27480 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
27490 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
274a0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
274b0 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
274c0 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
274d0 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
274e0 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
274f0 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
27500 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
27510 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
27520 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
27530 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
27540 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
27550 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
27560 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
27570 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
27580 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
27590 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
275a0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
275b0 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
275c0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
275d0 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
275e0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
275f0 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20  t encoding will 
27600 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74  be UTF-8 for dat
27610 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75  abases created u
27620 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  sing.** sqlite3_
27630 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
27640 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54  3_open_v2().  ^T
27650 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
27660 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65  ing for database
27670 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69  s.** created usi
27680 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  ng sqlite3_open1
27690 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  6() will be UTF-
276a0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
276b0 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a   byte order..**.
276c0 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
276d0 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
276e0 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
276f0 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
27700 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
27710 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
27720 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
27730 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
27740 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
27750 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
27760 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
27770 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
27780 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
27790 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
277a0 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
277b0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
277c0 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
277d0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
277e0 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
277f0 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
27800 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
27810 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
27820 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
27830 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68  onnection.  ^(Th
27840 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
27850 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
27860 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61  open_v2() can ta
27870 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
27880 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
27890 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
278a0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
278b0 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
278c0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
278d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
278e0 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  LLMUTEX], [SQLIT
278f0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
27900 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  HE],.** [SQLITE_
27910 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
27920 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  E], and/or [SQLI
27930 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
27940 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  gs:)^.**.** <dl>
27950 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
27960 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
27970 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
27980 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
27990 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79  ned in read-only
279a0 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64   mode.  If the d
279b0 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
279c0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73  .** already exis
279d0 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
279e0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
279f0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
27a00 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
27a10 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
27a20 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
27a30 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
27a40 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
27a50 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
27a60 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
27a70 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
27a80 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
27a90 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
27aa0 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
27ab0 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
27ac0 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
27ad0 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
27ae0 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
27af0 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
27b00 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
27b10 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
27b20 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
27b30 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
27b40 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
27b50 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
27b60 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
27b70 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
27b80 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74  created if.** it
27b90 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
27ba0 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
27bb0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
27bc0 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
27bd0 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
27be0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
27bf0 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
27c00 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
27c10 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
27c20 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
27c30 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
27c40 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
27c50 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
27c60 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69  shown above opti
27c70 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
27c80 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53  with other.** [S
27c90 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
27ca0 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45  NLY | SQLITE_OPE
27cb0 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65  N_* bits].** the
27cc0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
27cd0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
27ce0 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
27cf0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
27d00 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68   flag is set, th
27d10 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
27d20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70  connection.** op
27d30 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69  ens in the multi
27d40 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
27d50 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67  ng mode] as long
27d60 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74   as the single-t
27d70 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61  hread.** mode ha
27d80 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61  s not been set a
27d90 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
27da0 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e  r start-time.  ^
27db0 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
27dc0 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
27dd0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68  ] flag is set th
27de0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
27df0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73  connection opens
27e00 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61  .** in the seria
27e10 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
27e20 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69   mode] unless si
27e30 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a  ngle-thread was.
27e40 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
27e50 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c  lected at compil
27e60 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
27e70 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  time..** ^The [S
27e80 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
27e90 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  DCACHE] flag cau
27ea0 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
27eb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62   connection to b
27ec0 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f  e.** eligible to
27ed0 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63   use [shared cac
27ee0 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64  he mode], regard
27ef0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
27f00 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a  or not shared.**
27f10 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
27f20 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
27f30 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
27f40 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a  ache()].  ^The.*
27f50 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
27f60 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
27f70 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
27f80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
27f90 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69   to not.** parti
27fa0 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65  cipate in [share
27fb0 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76  d cache mode] ev
27fc0 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62  en if it is enab
27fd0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
27fe0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
27ff0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
28000 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
28010 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
28020 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
28030 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
28040 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
28050 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
28060 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74  t.** the new dat
28070 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
28080 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49   should use.  ^I
28090 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
280a0 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
280b0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
280c0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
280d0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
280e0 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
280f0 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
28100 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  e is ":memory:",
28110 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
28120 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65   temporary in-me
28130 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mory database.**
28140 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
28150 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
28160 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79   ^This in-memory
28170 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76   database will v
28180 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68  anish when.** th
28190 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
281a0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
281b0 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
281c0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
281d0 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66  t.** make use of
281e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63   additional spec
281f0 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68  ial filenames th
28200 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68  at begin with th
28210 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e  e ":" character.
28220 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d  .** It is recomm
28230 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20  ended that when 
28240 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  a database filen
28250 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65  ame actually doe
28260 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20  s begin with.** 
28270 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20  a ":" character 
28280 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69  you should prefi
28290 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77  x the filename w
282a0 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73  ith a pathname s
282b0 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74  uch as.** "./" t
282c0 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74  o avoid ambiguit
282d0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  y..**.** ^If the
282e0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20   filename is an 
282f0 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
28300 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
28310 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69  mporary.** on-di
28320 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
28330 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54   be created.  ^T
28340 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
28350 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
28360 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
28370 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
28380 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
28390 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
283a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  ed..**.** [[URI 
283b0 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c  filenames in sql
283c0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68  ite3_open()]] <h
283d0 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c  3>URI Filenames<
283e0 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b  /h3>.**.** ^If [
283f0 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e  URI filename] in
28400 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
28410 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65  enabled, and the
28420 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
28430 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74  nt.** begins wit
28440 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20  h "file:", then 
28450 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
28460 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
28470 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69   URI. ^URI.** fi
28480 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
28490 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
284a0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
284b0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
284c0 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20  s.** set in the 
284d0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
284e0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
284f0 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61  2(), or if it ha
28500 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65  s.** been enable
28510 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67  d globally using
28520 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
28530 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20  FIG_URI] option 
28540 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  with the.** [sql
28550 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d  ite3_config()] m
28560 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20  ethod or by the 
28570 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
28580 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
28590 74 69 6f 6e 2e 0a 2a 2a 20 55 52 49 20 66 69 6c  tion..** URI fil
285a0 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
285b0 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
285c0 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  ff.** by default
285d0 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c  , but future rel
285e0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20  eases of SQLite 
285f0 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49  might enable URI
28600 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74   filename.** int
28610 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64  erpretation by d
28620 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55  efault.  See "[U
28630 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66  RI filenames]" f
28640 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
28650 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
28660 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
28670 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63  s are parsed acc
28680 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39  ording to RFC 39
28690 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20  86. ^If the URI 
286a0 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61  contains an.** a
286b0 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69  uthority, then i
286c0 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
286d0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
286e0 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a   or the string .
286f0 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20  ** "localhost". 
28700 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74  ^If the authorit
28710 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74  y is not an empt
28720 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63  y string or "loc
28730 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20  alhost", an .** 
28740 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
28750 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e  d to the caller.
28760 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63   ^The fragment c
28770 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
28780 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e  I, if .** presen
28790 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  t, is ignored..*
287a0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
287b0 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f  s the path compo
287c0 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20  nent of the URI 
287d0 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  as the name of t
287e0 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20  he disk file.** 
287f0 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74  which contains t
28800 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66  he database. ^If
28810 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73   the path begins
28820 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72   with a '/' char
28830 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20  acter, .** then 
28840 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  it is interprete
28850 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65  d as an absolute
28860 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70   path. ^If the p
28870 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67  ath does not beg
28880 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f  in .** with a '/
28890 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20  ' (meaning that 
288a0 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65  the authority se
288b0 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ction is omitted
288c0 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a   from the URI).*
288d0 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20  * then the path 
288e0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
288f0 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  s a relative pat
28900 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64  h. .** ^(On wind
28910 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63  ows, the first c
28920 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61  omponent of an a
28930 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a  bsolute path .**
28940 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63   is a drive spec
28950 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20  ification (e.g. 
28960 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  "C:").)^.**.** [
28970 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
28980 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
28990 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
289a0 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
289b0 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
289c0 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
289d0 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
289e0 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
289f0 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
28a00 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
28a10 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
28a20 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74  ** SQLite and it
28a30 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65  s built-in [VFSe
28a40 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65  s] interpret the
28a50 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75  .** following qu
28a60 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a  ery parameters:.
28a70 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  **.** <ul>.**   
28a80 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a  <li> <b>vfs</b>:
28a90 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61   ^The "vfs" para
28aa0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65  meter may be use
28ab0 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  d to specify the
28ac0 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20   name of.**     
28ad0 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61  a VFS object tha
28ae0 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f  t provides the o
28af0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
28b00 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73  interface that s
28b10 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20  hould.**     be 
28b20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74  used to access t
28b30 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
28b40 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68   on disk. ^If th
28b50 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  is option is set
28b60 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d   to.**     an em
28b70 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64  pty string the d
28b80 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63  efault VFS objec
28b90 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63  t is used. ^Spec
28ba0 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
28bb0 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20  n.**     VFS is 
28bc0 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71  an error. ^If sq
28bd0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
28be0 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
28bf0 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  vfs option is.**
28c00 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68       present, th
28c10 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69  en the VFS speci
28c20 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69  fied by the opti
28c30 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65  on takes precede
28c40 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20  nce over.**     
28c50 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
28c60 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70   as the fourth p
28c70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
28c80 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
28c90 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d  *.**   <li> <b>m
28ca0 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d  ode</b>: ^(The m
28cb0 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ode parameter ma
28cc0 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
28cd0 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a  er "ro", "rw",.*
28ce0 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20  *     "rwc", or 
28cf0 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70  "memory". Attemp
28d00 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74  ting to set it t
28d10 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75  o any other valu
28d20 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65  e is.**     an e
28d30 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20  rror)^. .**     
28d40 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63  ^If "ro" is spec
28d50 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ified, then the 
28d60 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
28d70 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ed for read-only
28d80 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
28d90 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20   just as if the 
28da0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
28db0 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20  DONLY] flag had 
28dc0 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20  been set in the 
28dd0 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72  .**     third ar
28de0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
28df0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66  3_open_v2(). ^If
28e00 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
28e10 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20   is set to .**  
28e20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68     "rw", then th
28e30 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
28e40 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72  ened for read-wr
28e50 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65  ite (but not cre
28e60 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63  ate) .**     acc
28e70 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54  ess, as if SQLIT
28e80 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
28e90 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45   (but not SQLITE
28ea0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61  _OPEN_CREATE) ha
28eb0 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73  d .**     been s
28ec0 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22  et. ^Value "rwc"
28ed0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
28ee0 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a  o setting both .
28ef0 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
28f00 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64  EN_READWRITE and
28f10 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
28f20 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  ATE.  ^If the mo
28f30 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  de option is.** 
28f40 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f      set to "memo
28f50 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20  ry" then a pure 
28f60 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62  [in-memory datab
28f70 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20  ase] that never 
28f80 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20  reads.**     or 
28f90 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b  writes from disk
28fa0 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73   is used. ^It is
28fb0 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65   an error to spe
28fc0 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72  cify a value for
28fd0 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65  .**     the mode
28fe0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
28ff0 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74  is less restrict
29000 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70  ive than that sp
29010 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20  ecified by.**   
29020 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73    the flags pass
29030 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  ed in the third 
29040 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
29050 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
29060 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
29070 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  cache</b>: ^The 
29080 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
29090 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
290a0 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72  ther "shared" or
290b0 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65  .**     "private
290c0 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74  ". ^Setting it t
290d0 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71  o "shared" is eq
290e0 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
290f0 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53  ing the.**     S
29100 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
29110 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68  DCACHE bit in th
29120 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
29130 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20   passed to.**   
29140 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76    sqlite3_open_v
29150 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68  2(). ^Setting th
29160 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
29170 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69  r to "private" i
29180 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61  s .**     equiva
29190 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
291a0 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
291b0 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74  PRIVATECACHE bit
291c0 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c  ..**     ^If sql
291d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
291e0 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22  s used and the "
291f0 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72  cache" parameter
29200 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a   is present in.*
29210 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65  *     a URI file
29220 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20  name, its value 
29230 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65  overrides any be
29240 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64  havior requested
29250 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20   by setting.**  
29260 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50     SQLITE_OPEN_P
29270 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53  RIVATECACHE or S
29280 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
29290 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a  DCACHE flag..**.
292a0 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77  **  <li> <b>psow
292b0 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20  </b>: ^The psow 
292c0 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61  parameter indica
292d0 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e  tes whether or n
292e0 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70  ot the.**     [p
292f0 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69  owersafe overwri
29300 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65  te] property doe
29310 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70  s or does not ap
29320 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ply to the.**   
29330 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20    storage media 
29340 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74  on which the dat
29350 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64  abase file resid
29360 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  es..**.**  <li> 
29370 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e  <b>nolock</b>: ^
29380 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d  The nolock param
29390 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61  eter is a boolea
293a0 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  n query paramete
293b0 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69  r.**     which i
293c0 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66  f set disables f
293d0 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72  ile locking in r
293e0 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20  ollback journal 
293f0 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20  modes.  This.** 
29400 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f      is useful fo
29410 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61  r accessing a da
29420 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65  tabase on a file
29430 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73  system that does
29440 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70   not.**     supp
29450 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61  ort locking.  Ca
29460 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65  ution:  Database
29470 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68   corruption migh
29480 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a  t result if two.
29490 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70  **     or more p
294a0 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74  rocesses write t
294b0 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
294c0 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20  ase and any one 
294d0 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20  of those.**     
294e0 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e  processes uses n
294f0 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20  olock=1..**.**  
29500 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c  <li> <b>immutabl
29510 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75  e</b>: ^The immu
29520 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20  table parameter 
29530 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65  is a boolean que
29540 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65  ry.**     parame
29550 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74  ter that indicat
29560 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  es that the data
29570 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f  base file is sto
29580 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65  red on.**     re
29590 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20  ad-only media.  
295a0 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20  ^When immutable 
295b0 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61  is set, SQLite a
295c0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
295d0 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20  **     database 
295e0 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63  file cannot be c
295f0 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20  hanged, even by 
29600 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68  a process with h
29610 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69  igher.**     pri
29620 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74  vilege, and so t
29630 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
29640 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20  pened read-only 
29650 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a  and all locking.
29660 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67  **     and chang
29670 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64  e detection is d
29680 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f  isabled.  Cautio
29690 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69  n: Setting the i
296a0 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20  mmutable.**     
296b0 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61  property on a da
296c0 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74  tabase file that
296d0 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68   does in fact ch
296e0 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a  ange can result.
296f0 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72  **     in incorr
29700 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  ect query result
29710 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  s and/or [SQLITE
29720 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73  _CORRUPT] errors
29730 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73  ..**     See als
29740 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  o: [SQLITE_IOCAP
29750 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20  _IMMUTABLE]..** 
29760 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a        .** </ul>.
29770 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e  **.** ^Specifyin
29780 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72  g an unknown par
29790 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75  ameter in the qu
297a0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
297b0 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e   a URI is not an
297c0 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75  .** error.  Futu
297d0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
297e0 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65  QLite might unde
297f0 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61  rstand additiona
29800 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  l query.** param
29810 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75  eters.  See "[qu
29820 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77  ery parameters w
29830 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e  ith special mean
29840 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20  ing to SQLite]" 
29850 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
29860 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
29870 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
29880 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c  ame examples]] <
29890 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  h3>URI filename 
298a0 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a  examples</h3>.**
298b0 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
298c0 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74  r="1" align=cent
298d0 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35  er cellpadding=5
298e0 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52  >.** <tr><th> UR
298f0 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e  I filenames <th>
29900 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e   Results.** <tr>
29910 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
29920 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
29930 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c      Open the fil
29940 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
29950 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
29960 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tory..** <tr><td
29970 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
29980 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a  d/data.db<br>.**
29990 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
299a0 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  //home/fred/data
299b0 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20  .db <br> .**    
299c0 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63        file://loc
299d0 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64  alhost/home/fred
299e0 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74  /data.db <br> <t
299f0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
29a00 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  Open the databas
29a10 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  e file "/home/fr
29a20 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20  ed/data.db"..** 
29a30 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f  <tr><td> file://
29a40 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72  darkstar/home/fr
29a50 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  ed/data.db <td> 
29a60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
29a70 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72  error. "darkstar
29a80 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67  " is not a recog
29a90 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e  nized authority.
29aa0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c  .** <tr><td styl
29ab0 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e  e="white-space:n
29ac0 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20  owrap"> .**     
29ad0 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f       file:///C:/
29ae0 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25  Documents%20and%
29af0 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f  20Settings/fred/
29b00 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a  Desktop/data.db.
29b10 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64  **     <td> Wind
29b20 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74  ows only: Open t
29b30 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
29b40 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b  " on fred's desk
29b50 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20  top on drive.** 
29b60 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74           C:. Not
29b70 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65  e that the %20 e
29b80 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20  scaping in this 
29b90 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73  example is not s
29ba0 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20  trictly .**     
29bb0 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d       necessary -
29bc0 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72   space character
29bd0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69  s can be used li
29be0 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20  terally.**      
29bf0 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e      in URI filen
29c00 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ames..** <tr><td
29c10 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
29c20 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69  ode=ro&cache=pri
29c30 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  vate <td> .**   
29c40 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
29c50 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
29c60 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
29c70 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ory for read-onl
29c80 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20  y access..**    
29c90 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73        Regardless
29ca0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
29cb0 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20  ot shared-cache 
29cc0 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20  mode is enabled 
29cd0 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  by.**          d
29ce0 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72  efault, use a pr
29cf0 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20  ivate cache..** 
29d00 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
29d10 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
29d20 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c  ?vfs=unix-dotfil
29d30 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20  e <td>.**       
29d40 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68     Open file "/h
29d50 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
29d60 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69  ". Use the speci
29d70 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74  al VFS "unix-dot
29d80 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20  file".**        
29d90 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d    that uses dot-
29da0 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f  files in place o
29db0 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79  f posix advisory
29dc0 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72   locking..** <tr
29dd0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
29de0 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79  db?mode=readonly
29df0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
29e00 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65     An error. "re
29e10 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61  adonly" is not a
29e20 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f   valid option fo
29e30 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72  r the "mode" par
29e40 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62  ameter..** </tab
29e50 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68  le>.**.** ^URI h
29e60 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
29e70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48  e sequences (%HH
29e80 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  ) are supported 
29e90 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20  within the path 
29ea0 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d  and.** query com
29eb0 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49  ponents of a URI
29ec0 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20  . A hexadecimal 
29ed0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20  escape sequence 
29ee0 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a  consists of a.**
29ef0 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20   percent sign - 
29f00 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62  "%" - followed b
29f10 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65  y exactly two he
29f20 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73  xadecimal digits
29f30 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20   .** specifying 
29f40 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20  an octet value. 
29f50 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68  ^Before the path
29f60 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e   or query compon
29f70 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49  ents of a.** URI
29f80 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e   filename are in
29f90 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20  terpreted, they 
29fa0 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  are encoded usin
29fb0 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20  g UTF-8 and all 
29fc0 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20  .** hexadecimal 
29fd0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
29fe0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73   replaced by a s
29ff0 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61  ingle byte conta
2a000 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72  ining the.** cor
2a010 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74  responding octet
2a020 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73  . If this proces
2a030 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69  s generates an i
2a040 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63  nvalid UTF-8 enc
2a050 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65  oding,.** the re
2a060 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2a070 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ned..**.** <b>No
2a080 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
2a090 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
2a0a0 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
2a0b0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
2a0c0 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
2a0d0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
2a0e0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
2a0f0 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
2a100 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
2a110 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
2a120 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
2a130 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
2a140 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
2a150 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
2a160 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
2a170 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
2a180 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
2a190 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
2a1a0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
2a1b0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
2a1c0 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
2a1d0 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20  Windows Runtime 
2a1e0 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
2a1f0 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74  temporary direct
2a200 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a  ory must be set.
2a210 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
2a220 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
2a230 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
2a240 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77  en_v2().  Otherw
2a250 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20  ise, various.** 
2a260 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65  features that re
2a270 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66  quire the use of
2a280 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
2a290 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a   may fail..**.**
2a2a0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2a2b0 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
2a2c0 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ry].*/.int sqlit
2a2d0 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
2a2e0 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
2a2f0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
2a300 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
2a310 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
2a320 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
2a330 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
2a340 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
2a350 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
2a360 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
2a370 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
2a380 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
2a390 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
2a3a0 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
2a3b0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
2a3c0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
2a3d0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2a3e0 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
2a3f0 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
2a400 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
2a410 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
2a420 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
2a430 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
2a440 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
2a450 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
2a460 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
2a470 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
2a480 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
2a490 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
2a4a0 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
2a4b0 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
2a4c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
2a4d0 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55  ain Values For U
2a4e0 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  RI Parameters.**
2a4f0 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74  .** These are ut
2a500 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20  ility routines, 
2a510 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d  useful to VFS im
2a520 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74  plementations, t
2a530 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20  hat check.** to 
2a540 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73  see if a databas
2a550 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49  e file was a URI
2a560 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20   that contained 
2a570 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79  a specific query
2a580 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20   .** parameter, 
2a590 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e  and if so obtain
2a5a0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
2a5b0 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65  hat query parame
2a5c0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20  ter..**.** If F 
2a5d0 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  is the database 
2a5e0 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72  filename pointer
2a5f0 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
2a600 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20   xOpen() method 
2a610 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70  of .** a VFS imp
2a620 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e  lementation when
2a630 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   the flags param
2a640 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20  eter to xOpen() 
2a650 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d  has one or .** m
2a660 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ore of the [SQLI
2a670 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20  TE_OPEN_URI] or 
2a680 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
2a690 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61  N_DB] bits set a
2a6a0 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e  nd.** P is the n
2a6b0 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79  ame of the query
2a6c0 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
2a6d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
2a6e0 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
2a6f0 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
2a700 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72   of the P.** par
2a710 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69  ameter if it exi
2a720 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  sts or a NULL po
2a730 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20  inter if P does 
2a740 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20  not appear as a 
2a750 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
2a760 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20  ter on F.  If P 
2a770 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d  is a query param
2a780 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73  eter of F.** has
2a790 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c   no explicit val
2a7a0 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ue, then sqlite3
2a7b0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
2a7c0 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ,P) returns.** a
2a7d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65   pointer to an e
2a7e0 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  mpty string..**.
2a7f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
2a800 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
2a810 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65  ) routine assume
2a820 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f  s that P is a bo
2a830 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74  olean.** paramet
2a840 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
2a850 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65  rue (1) or false
2a860 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74   (0) according t
2a870 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f  o the value.** o
2a880 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65  f P.  The sqlite
2a890 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
2a8a0 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74  P,B) routine ret
2a8b0 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66  urns true (1) if
2a8c0 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
2a8d0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
2a8e0 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65   P is one of "ye
2a8f0 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22  s", "true", or "
2a900 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61  on" in any.** ca
2a910 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c  se or if the val
2a920 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
2a930 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72   non-zero number
2a940 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74  .  The .** sqlit
2a950 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
2a960 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72  ,P,B) routines r
2a970 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29  eturns false (0)
2a980 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
2a990 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
2a9a0 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
2a9b0 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f  "no", "false", o
2a9c0 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63  r "off" in any c
2a9d0 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65  ase or.** if the
2a9e0 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
2a9f0 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72  th a numeric zer
2aa00 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20  o.  If P is not 
2aa10 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  a query.** param
2aa20 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20  eter on F or if 
2aa30 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
2aa40 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68  s does not match
2aa50 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61   any of the.** a
2aa60 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  bove, then sqlit
2aa70 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
2aa80 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42  ,P,B) returns (B
2aa90 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  !=0)..**.** The 
2aaa0 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
2aab0 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65  4(F,P,D) routine
2aac0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61   converts the va
2aad0 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a  lue of P into a.
2aae0 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ** 64-bit signed
2aaf0 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74   integer and ret
2ab00 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65  urns that intege
2ab10 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65  r, or D if P doe
2ab20 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20  s not.** exist. 
2ab30 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   If the value of
2ab40 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20   P is something 
2ab50 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e  other than an in
2ab60 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a  teger, then.** z
2ab70 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
2ab80 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20  .** .** If F is 
2ab90 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
2aba0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
2abb0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
2abc0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
2abd0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
2abe0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
2abf0 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20  eturns B.  If F 
2ac00 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f  is not a NULL po
2ac10 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20  inter and.** is 
2ac20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
2ac30 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69  ile pathname poi
2ac40 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  nter that SQLite
2ac50 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
2ac60 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65   xOpen.** VFS me
2ac70 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62  thod, then the b
2ac80 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20  ehavior of this 
2ac90 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66  routine is undef
2aca0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
2acb0 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  y.** undesirable
2acc0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20  ..**.** See the 
2acd0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 64  [URI filename] d
2ace0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
2acf0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
2ad00 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 63 6f 6e 73  rmation..*/.cons
2ad10 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2ad20 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
2ad30 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
2ad40 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
2ad50 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71  *zParam);.int sq
2ad60 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
2ad70 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  n(const char *zF
2ad80 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ile, const char 
2ad90 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65  *zParam, int bDe
2ada0 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f  fault);.sqlite3_
2adb0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72  int64 sqlite3_ur
2adc0 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68  i_int64(const ch
2add0 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  ar*, const char*
2ade0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
2adf0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
2ae00 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
2ae10 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20  And Messages.** 
2ae20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
2ae30 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
2ae40 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65  st recent sqlite
2ae50 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73  3_* API call ass
2ae60 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a  ociated with .**
2ae70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2ae80 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c  ction] D failed,
2ae90 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
2aea0 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74  3_errcode(D) int
2aeb0 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e  erface.** return
2aec0 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
2aed0 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b  esult code] or [
2aee0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
2aef0 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a  code] for that.*
2af00 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 5e  * API call..** ^
2af10 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
2af20 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
2af30 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
2af40 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
2af50 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
2af60 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
2af70 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
2af80 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
2af90 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
2afa0 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
2afb0 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bled..**.** The 
2afc0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
2afd0 62 79 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  by sqlite3_errco
2afe0 64 65 28 29 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  de() and/or.** s
2aff0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
2b000 65 72 72 63 6f 64 65 28 29 20 6d 69 67 68 74 20  errcode() might 
2b010 63 68 61 6e 67 65 20 77 69 74 68 20 65 61 63 68  change with each
2b020 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 45 78   API call..** Ex
2b030 63 65 70 74 2c 20 74 68 65 72 65 20 61 72 65 20  cept, there are 
2b040 73 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  some interfaces 
2b050 74 68 61 74 20 61 72 65 20 67 75 61 72 61 6e 74  that are guarant
2b060 65 65 64 20 74 6f 20 6e 65 76 65 72 0a 2a 2a 20  eed to never.** 
2b070 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
2b080 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 63 6f   of the error co
2b090 64 65 2e 20 20 54 68 65 20 65 72 72 6f 72 2d 63  de.  The error-c
2b0a0 6f 64 65 20 70 72 65 73 65 72 76 69 6e 67 0a 2a  ode preserving.*
2b0b0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
2b0c0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
2b0d0 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65 72 72  <li> sqlite3_err
2b0e0 63 6f 64 65 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73  code().** <li> s
2b0f0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
2b100 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 3c 6c 69  errcode().** <li
2b110 3e 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  > sqlite3_errmsg
2b120 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74  ().** <li> sqlit
2b130 65 33 5f 65 72 72 6d 73 67 31 36 28 29 0a 2a 2a  e3_errmsg16().**
2b140 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68   </ul>.**.** ^Th
2b150 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
2b160 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
2b170 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
2b180 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
2b190 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
2b1a0 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
2b1b0 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
2b1c0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
2b1d0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
2b1e0 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
2b1f0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
2b200 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
2b210 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
2b220 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
2b230 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
2b240 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
2b250 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
2b260 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
2b270 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
2b280 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
2b290 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
2b2a0 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
2b2b0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
2b2c0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
2b2d0 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
2b2e0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
2b2f0 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69  lite3_errstr() i
2b300 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2b310 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e   the English-lan
2b320 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68  guage text.** th
2b330 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
2b340 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20   [result code], 
2b350 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d  as UTF-8..** ^(M
2b360 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
2b370 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
2b380 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
2b390 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  d internally.** 
2b3a0 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  and must not be 
2b3b0 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70  freed by the app
2b3c0 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a  lication)^..**.*
2b3d0 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
2b3e0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
2b3f0 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
2b400 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
2b410 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
2b420 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
2b430 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
2b440 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
2b450 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
2b460 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
2b470 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
2b480 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
2b490 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
2b4a0 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
2b4b0 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
2b4c0 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
2b4d0 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
2b4e0 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
2b4f0 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
2b500 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
2b510 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
2b520 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
2b530 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
2b540 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
2b550 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b560 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
2b570 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
2b580 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
2b590 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
2b5a0 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
2b5b0 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
2b5c0 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
2b5d0 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
2b5e0 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
2b5f0 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
2b600 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
2b610 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
2b620 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
2b630 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
2b640 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
2b650 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
2b660 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
2b670 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
2b680 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
2b690 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
2b6a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
2b6b0 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
2b6c0 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
2b6d0 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
2b6e0 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
2b6f0 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  et..*/.int sqlit
2b700 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
2b710 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c  e3 *db);.int sql
2b720 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
2b730 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
2b740 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  b);.const char *
2b750 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
2b760 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
2b770 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72  void *sqlite3_er
2b780 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29  rmsg16(sqlite3*)
2b790 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
2b7a0 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74  lite3_errstr(int
2b7b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b7c0 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 61  EF: Prepared Sta
2b7d0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
2b7e0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70   KEYWORDS: {prep
2b7f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20  ared statement} 
2b800 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
2b810 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ents}.**.** An i
2b820 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
2b830 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
2b840 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  s a single SQL s
2b850 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a  tatement that.**
2b860 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c   has been compil
2b870 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66  ed into binary f
2b880 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79  orm and is ready
2b890 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
2b8a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66  ..**.** Think of
2b8b0 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
2b8c0 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61 74  ent as a separat
2b8d0 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72  e computer progr
2b8e0 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67  am.  The.** orig
2b8f0 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73  inal SQL text is
2b900 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41   source code.  A
2b910 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2b920 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69  ent object .** i
2b930 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f  s the compiled o
2b940 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c  bject code.  All
2b950 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e   SQL must be con
2b960 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a  verted into a.**
2b970 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2b980 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63 61  ent before it ca
2b990 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20  n be run..**.** 
2b9a0 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f  The life-cycle o
2b9b0 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  f a prepared sta
2b9c0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73  tement object us
2b9d0 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20  ually goes like 
2b9e0 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
2b9f0 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
2ba00 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
2ba10 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73  tement object us
2ba20 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
2ba30 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c  pare_v2()]..** <
2ba40 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
2ba50 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20  to [parameters] 
2ba60 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
2ba70 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
2ba80 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
2ba90 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
2baa0 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
2bab0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
2bac0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
2bad0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
2bae0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
2baf0 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
2bb00 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
2bb10 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20  hen go back.**  
2bb20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20      to step 2.  
2bb30 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20  Do this zero or 
2bb40 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
2bb50 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20  li> Destroy the 
2bb60 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
2bb70 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2bb80 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74  ]..** </ol>.*/.t
2bb90 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2bba0 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
2bbb0 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
2bbc0 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
2bbd0 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54  me Limits.** MET
2bbe0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
2bbf0 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
2bc00 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
2bc10 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
2bc20 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
2bc30 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
2bc40 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
2bc50 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
2bc60 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
2bc70 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
2bc80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2bc90 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
2bca0 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
2bcb0 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
2bcc0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
2bcd0 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
2bce0 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
2bcf0 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
2bd00 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
2bd10 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
2bd20 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
2bd30 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2bd40 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
2bd50 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
2bd60 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a  onstruct.)^.**.*
2bd70 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69  * ^If the new li
2bd80 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
2bd90 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
2bda0 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
2bdb0 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20  ..** ^(For each 
2bdc0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53  limit category S
2bdd0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e  QLITE_LIMIT_<i>N
2bde0 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73  AME</i> there is
2bdf0 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
2be00 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
2be10 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d  d].** set at com
2be20 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43  pile-time by a C
2be30 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
2be40 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c  cro called.** [l
2be50 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
2be60 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e  AX_<i>NAME</i>].
2be70 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
2be80 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
2be90 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
2bea0 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74  AX_".))^.** ^Att
2beb0 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
2bec0 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
2bed0 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
2bee0 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
2bef0 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
2bf00 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
2bf10 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52   bound..**.** ^R
2bf20 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
2bf30 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
2bf40 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65  limit was change
2bf50 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  d, the .** [sqli
2bf60 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74  te3_limit()] int
2bf70 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2bf80 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
2bf90 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  f the limit..** 
2bfa0 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20  ^Hence, to find 
2bfb0 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
2bfc0 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74  e of a limit wit
2bfd0 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74  hout changing it
2bfe0 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f  ,.** simply invo
2bff0 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ke this interfac
2c000 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64  e with the third
2c010 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74   parameter set t
2c020 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d  o -1..**.** Run-
2c030 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
2c040 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2c050 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
2c060 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
2c070 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
2c080 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
2c090 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
2c0a0 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
2c0b0 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
2c0c0 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
2c0d0 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
2c0e0 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
2c0f0 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
2c100 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74  web browser that
2c110 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
2c120 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
2c130 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
2c140 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
2c150 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
2c160 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
2c170 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
2c180 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
2c190 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
2c1a0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
2c1b0 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
2c1c0 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
2c1d0 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
2c1e0 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
2c1f0 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
2c200 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
2c210 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
2c220 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
2c230 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
2c240 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
2c250 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
2c260 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
2c270 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
2c280 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
2c290 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
2c2a0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
2c2b0 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
2c2c0 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
2c2d0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
2c2e0 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
2c2f0 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
2c300 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
2c310 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
2c320 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
2c330 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
2c340 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
2c350 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
2c360 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
2c370 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
2c380 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eases..*/.int sq
2c390 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69  lite3_limit(sqli
2c3a0 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e  te3*, int id, in
2c3b0 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a  t newVal);../*.*
2c3c0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
2c3d0 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67  Time Limit Categ
2c3e0 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ories.** KEYWORD
2c3f0 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  S: {limit catego
2c400 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65  ry} {*limit cate
2c410 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  gories}.**.** Th
2c420 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ese constants de
2c430 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72  fine various per
2c440 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a  formance limits.
2c450 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c  ** that can be l
2c460 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69  owered at run-ti
2c470 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  me using [sqlite
2c480 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
2c490 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74  he synopsis of t
2c4a0 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
2c4b0 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
2c4c0 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77  s is shown below
2c4d0 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20  ..** Additional 
2c4e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61  information is a
2c4f0 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d  vailable at [lim
2c500 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20  its | Limits in 
2c510 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  SQLite]..**.** <
2c520 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
2c530 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e  LIMIT_LENGTH]] ^
2c540 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2c550 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  T_LENGTH</dt>.**
2c560 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2c570 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72   size of any str
2c580 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74  ing or BLOB or t
2c590 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74  able row, in byt
2c5a0 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  es.<dd>)^.**.** 
2c5b0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  [[SQLITE_LIMIT_S
2c5c0 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  QL_LENGTH]] ^(<d
2c5d0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  t>SQLITE_LIMIT_S
2c5e0 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  QL_LENGTH</dt>.*
2c5f0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2c600 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53  m length of an S
2c610 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e  QL statement, in
2c620 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a   bytes.</dd>)^.*
2c630 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2c640 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c  MIT_COLUMN]] ^(<
2c650 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2c660 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
2c670 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
2c680 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2c690 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
2c6a0 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
2c6b0 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
2c6c0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20  f a [SELECT] or 
2c6d0 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
2c6e0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2c6f0 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20   an index.** or 
2c700 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f  in an ORDER BY o
2c710 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
2c720 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
2c730 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  [[SQLITE_LIMIT_E
2c740 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  XPR_DEPTH]] ^(<d
2c750 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  t>SQLITE_LIMIT_E
2c760 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  XPR_DEPTH</dt>.*
2c770 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2c780 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70  m depth of the p
2c790 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79  arse tree on any
2c7a0 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64   expression.</dd
2c7b0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2c7c0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
2c7d0 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74  D_SELECT]] ^(<dt
2c7e0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
2c7f0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
2c800 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2c810 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
2c820 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
2c830 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
2c840 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ment.</dd>)^.**.
2c850 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2c860 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64  T_VDBE_OP]] ^(<d
2c870 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
2c880 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
2c890 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
2c8a0 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
2c8b0 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
2c8c0 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
2c8d0 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
2c8e0 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
2c8f0 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 5b 73  tatement.  If [s
2c900 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2c910 32 28 29 5d 20 6f 72 0a 2a 2a 20 74 68 65 20 65  2()] or.** the e
2c920 71 75 69 76 61 6c 65 6e 74 20 74 72 69 65 73 20  quivalent tries 
2c930 74 6f 20 61 6c 6c 6f 63 61 74 65 20 73 70 61 63  to allocate spac
2c940 65 20 66 6f 72 20 6d 6f 72 65 20 74 68 61 6e 20  e for more than 
2c950 74 68 69 73 20 6d 61 6e 79 20 6f 70 63 6f 64 65  this many opcode
2c960 73 0a 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c 65  s.** in a single
2c970 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2c980 65 6e 74 2c 20 61 6e 20 53 51 4c 49 54 45 5f 4e  ent, an SQLITE_N
2c990 4f 4d 45 4d 20 65 72 72 6f 72 20 69 73 20 72 65  OMEM error is re
2c9a0 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
2c9b0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2c9c0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
2c9d0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2c9e0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
2c9f0 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  RG</dt>.** <dd>T
2ca00 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
2ca10 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f  r of arguments o
2ca20 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64  n a function.</d
2ca30 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2ca40 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
2ca50 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ED]] ^(<dt>SQLIT
2ca60 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
2ca70 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2ca80 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
2ca90 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74  of [ATTACH | att
2caa0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d  ached databases]
2cab0 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  .)^</dd>.**.** [
2cac0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  [SQLITE_LIMIT_LI
2cad0 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
2cae0 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  H]].** ^(<dt>SQL
2caf0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
2cb00 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64  ATTERN_LENGTH</d
2cb10 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2cb20 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2cb30 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75  the pattern argu
2cb40 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b  ment to the [LIK
2cb50 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20  E] or.** [GLOB] 
2cb60 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29  operators.</dd>)
2cb70 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2cb80 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
2cb90 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64  NUMBER]].** ^(<d
2cba0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
2cbb0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f  ARIABLE_NUMBER</
2cbc0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2cbd0 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d  aximum index num
2cbe0 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61  ber of any [para
2cbf0 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c  meter] in an SQL
2cc00 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a   statement.)^.**
2cc10 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2cc20 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
2cc30 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2cc40 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
2cc50 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
2cc60 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
2cc70 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66  h of recursion f
2cc80 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64  or triggers.</dd
2cc90 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2cca0 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
2ccb0 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e  THREADS]] ^(<dt>
2ccc0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52  SQLITE_LIMIT_WOR
2ccd0 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e  KER_THREADS</dt>
2cce0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2ccf0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75  mum number of au
2cd00 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74  xiliary worker t
2cd10 68 72 65 61 64 73 20 74 68 61 74 20 61 20 73 69  hreads that a si
2cd20 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65  ngle.** [prepare
2cd30 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79  d statement] may
2cd40 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a   start.</dd>)^.*
2cd50 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
2cd60 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2cd70 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
2cd80 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
2cd90 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2cda0 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20  _SQL_LENGTH     
2cdb0 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
2cdc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2cdd0 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20  T_COLUMN        
2cde0 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64              2.#d
2cdf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2ce00 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20  IT_EXPR_DEPTH   
2ce10 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23               3.#
2ce20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2ce30 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
2ce40 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a  ECT           4.
2ce50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2ce60 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20  IMIT_VDBE_OP    
2ce70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
2ce80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2ce90 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
2cea0 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RG              
2ceb0 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
2cec0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20  _LIMIT_ATTACHED 
2ced0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2cee0 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
2cef0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
2cf00 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20  TERN_LENGTH     
2cf10 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
2cf20 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
2cf30 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20  E_NUMBER        
2cf40 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
2cf50 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
2cf60 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
2cf70 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
2cf80 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
2cf90 52 5f 54 48 52 45 41 44 53 20 20 20 20 20 20 20  R_THREADS       
2cfa0 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41      11../*.** CA
2cfb0 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 20  PI3REF: Prepare 
2cfc0 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  Flags.**.** Thes
2cfd0 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
2cfe0 6e 65 20 76 61 72 69 6f 75 73 20 66 6c 61 67 73  ne various flags
2cff0 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 61 73   that can be pas
2d000 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 22 70 72 65  sed into.** "pre
2d010 70 46 6c 61 67 73 22 20 70 61 72 61 6d 65 74 65  pFlags" paramete
2d020 72 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  r of the [sqlite
2d030 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20  3_prepare_v3()] 
2d040 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2d050 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20  prepare16_v3()] 
2d060 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 0a 2a  interfaces..**.*
2d070 2a 20 4e 65 77 20 66 6c 61 67 73 20 6d 61 79 20  * New flags may 
2d080 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
2d090 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
2d0a0 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  QLite..**.** <dl
2d0b0 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 52  >.** [[SQLITE_PR
2d0c0 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54  EPARE_PERSISTENT
2d0d0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2d0e0 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45  PREPARE_PERSISTE
2d0f0 4e 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  NT</dt>.** <dd>T
2d100 68 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52  he SQLITE_PREPAR
2d110 45 5f 50 45 52 53 49 53 54 45 4e 54 20 66 6c 61  E_PERSISTENT fla
2d120 67 20 69 73 20 61 20 68 69 6e 74 20 74 6f 20 74  g is a hint to t
2d130 68 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  he query planner
2d140 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 65  .** that the pre
2d150 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2d160 77 69 6c 6c 20 62 65 20 72 65 74 61 69 6e 65 64  will be retained
2d170 20 66 6f 72 20 61 20 6c 6f 6e 67 20 74 69 6d 65   for a long time
2d180 20 61 6e 64 0a 2a 2a 20 70 72 6f 62 61 62 6c 79   and.** probably
2d190 20 72 65 75 73 65 64 20 6d 61 6e 79 20 74 69 6d   reused many tim
2d1a0 65 73 2e 29 5e 20 5e 57 69 74 68 6f 75 74 20 74  es.)^ ^Without t
2d1b0 68 69 73 20 66 6c 61 67 2c 20 5b 73 71 6c 69 74  his flag, [sqlit
2d1c0 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
2d1d0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2d1e0 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
2d1f0 20 61 73 73 75 6d 65 20 74 68 61 74 20 74 68 65   assume that the
2d200 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2d210 65 6e 74 20 77 69 6c 6c 20 0a 2a 2a 20 62 65 20  ent will .** be 
2d220 75 73 65 64 20 6a 75 73 74 20 6f 6e 63 65 20 6f  used just once o
2d230 72 20 61 74 20 6d 6f 73 74 20 61 20 66 65 77 20  r at most a few 
2d240 74 69 6d 65 73 20 61 6e 64 20 74 68 65 6e 20 64  times and then d
2d250 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67 0a 2a  estroyed using.*
2d260 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
2d270 69 7a 65 28 29 5d 20 72 65 6c 61 74 69 76 65 6c  ize()] relativel
2d280 79 20 73 6f 6f 6e 2e 20 54 68 65 20 63 75 72 72  y soon. The curr
2d290 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
2d2a0 6f 6e 20 61 63 74 73 0a 2a 2a 20 6f 6e 20 74 68  on acts.** on th
2d2b0 69 73 20 68 69 6e 74 20 62 79 20 61 76 6f 69 64  is hint by avoid
2d2c0 69 6e 67 20 74 68 65 20 75 73 65 20 6f 66 20 5b  ing the use of [
2d2d0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
2d2e0 5d 20 73 6f 20 61 73 20 6e 6f 74 20 74 6f 0a 2a  ] so as not to.*
2d2f0 2a 20 64 65 70 6c 65 74 65 20 74 68 65 20 6c 69  * deplete the li
2d300 6d 69 74 65 64 20 73 74 6f 72 65 20 6f 66 20 6c  mited store of l
2d310 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
2d320 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
2d330 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61   of.** SQLite ma
2d340 79 20 61 63 74 20 6f 6e 20 74 68 69 73 20 68 69  y act on this hi
2d350 6e 74 20 64 69 66 66 65 72 65 6e 74 6c 79 2e 0a  nt differently..
2d360 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50  **.** [[SQLITE_P
2d370 52 45 50 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45  REPARE_NORMALIZE
2d380 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52  ]] <dt>SQLITE_PR
2d390 45 50 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45 3c  EPARE_NORMALIZE<
2d3a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2d3b0 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e  SQLITE_PREPARE_N
2d3c0 4f 52 4d 41 4c 49 5a 45 20 66 6c 61 67 20 69 73  ORMALIZE flag is
2d3d0 20 61 20 6e 6f 2d 6f 70 2e 20 54 68 69 73 20 66   a no-op. This f
2d3e0 6c 61 67 20 75 73 65 64 0a 2a 2a 20 74 6f 20 62  lag used.** to b
2d3f0 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 61  e required for a
2d400 6e 79 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ny prepared stat
2d410 65 6d 65 6e 74 20 74 68 61 74 20 77 61 6e 74 65  ement that wante
2d420 64 20 74 6f 20 75 73 65 20 74 68 65 0a 2a 2a 20  d to use the.** 
2d430 5b 73 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69  [sqlite3_normali
2d440 7a 65 64 5f 73 71 6c 28 29 5d 20 69 6e 74 65 72  zed_sql()] inter
2d450 66 61 63 65 2e 20 20 48 6f 77 65 76 65 72 2c 20  face.  However, 
2d460 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
2d470 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 29  normalized_sql()
2d480 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ] interface is n
2d490 6f 77 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20  ow available to 
2d4a0 61 6c 6c 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  all.** prepared 
2d4b0 73 74 61 74 65 6d 65 6e 74 73 2c 20 72 65 67 61  statements, rega
2d4c0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
2d4d0 72 20 6f 72 20 6e 6f 74 20 74 68 65 79 20 75 73  r or not they us
2d4e0 65 20 74 68 69 73 0a 2a 2a 20 66 6c 61 67 2e 0a  e this.** flag..
2d4f0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50  **.** [[SQLITE_P
2d500 52 45 50 41 52 45 5f 4e 4f 5f 56 54 41 42 5d 5d  REPARE_NO_VTAB]]
2d510 20 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52 45 50   <dt>SQLITE_PREP
2d520 41 52 45 5f 4e 4f 5f 56 54 41 42 3c 2f 64 74 3e  ARE_NO_VTAB</dt>
2d530 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49  .** <dd>The SQLI
2d540 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 5f 56 54  TE_PREPARE_NO_VT
2d550 41 42 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  AB flag causes t
2d560 68 65 20 53 51 4c 20 63 6f 6d 70 69 6c 65 72 0a  he SQL compiler.
2d570 2a 2a 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 20  ** to return an 
2d580 65 72 72 6f 72 20 28 65 72 72 6f 72 20 63 6f 64  error (error cod
2d590 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 29 20  e SQLITE_ERROR) 
2d5a0 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
2d5b0 20 75 73 65 73 0a 2a 2a 20 61 6e 79 20 76 69 72   uses.** any vir
2d5c0 74 75 61 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a 20  tual tables..** 
2d5d0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
2d5e0 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f   SQLITE_PREPARE_
2d5f0 50 45 52 53 49 53 54 45 4e 54 20 20 20 20 20 20  PERSISTENT      
2d600 20 20 20 20 20 20 20 20 30 78 30 31 0a 23 64 65          0x01.#de
2d610 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 45 50  fine SQLITE_PREP
2d620 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45 20 20 20  ARE_NORMALIZE   
2d630 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 32              0x02
2d640 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2d650 50 52 45 50 41 52 45 5f 4e 4f 5f 56 54 41 42 20  PREPARE_NO_VTAB 
2d660 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d670 30 78 30 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0x04../*.** CAPI
2d680 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
2d690 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2d6a0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
2d6b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
2d6c0 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44  piler}.** METHOD
2d6d0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e  : sqlite3.** CON
2d6e0 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
2d6f0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20  3_stmt.**.** To 
2d700 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 73  execute an SQL s
2d710 74 61 74 65 6d 65 6e 74 2c 20 69 74 20 6d 75 73  tatement, it mus
2d720 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
2d730 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
2d740 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  code.** program 
2d750 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
2d760 73 65 20 72 6f 75 74 69 6e 65 73 2e 20 20 4f 72  se routines.  Or
2d770 2c 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  , in other words
2d780 2c 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  , these routines
2d790 0a 2a 2a 20 61 72 65 20 63 6f 6e 73 74 72 75 63  .** are construc
2d7a0 74 6f 72 73 20 66 6f 72 20 74 68 65 20 5b 70 72  tors for the [pr
2d7b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d7c0 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
2d7d0 54 68 65 20 70 72 65 66 65 72 72 65 64 20 72 6f  The preferred ro
2d7e0 75 74 69 6e 65 20 74 6f 20 75 73 65 20 69 73 20  utine to use is 
2d7f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d800 5f 76 32 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20  _v2()].  The.** 
2d810 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d820 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73  ()] interface is
2d830 20 6c 65 67 61 63 79 20 61 6e 64 20 73 68 6f 75   legacy and shou
2d840 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a  ld be avoided..*
2d850 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2d860 72 65 5f 76 33 28 29 5d 20 68 61 73 20 61 6e 20  re_v3()] has an 
2d870 65 78 74 72 61 20 22 70 72 65 70 46 6c 61 67 73  extra "prepFlags
2d880 22 20 6f 70 74 69 6f 6e 20 74 68 61 74 20 69 73  " option that is
2d890 20 75 73 65 64 0a 2a 2a 20 66 6f 72 20 73 70 65   used.** for spe
2d8a0 63 69 61 6c 20 70 75 72 70 6f 73 65 73 2e 0a 2a  cial purposes..*
2d8b0 2a 0a 2a 2a 20 54 68 65 20 75 73 65 20 6f 66 20  *.** The use of 
2d8c0 74 68 65 20 55 54 46 2d 38 20 69 6e 74 65 72 66  the UTF-8 interf
2d8d0 61 63 65 73 20 69 73 20 70 72 65 66 65 72 72 65  aces is preferre
2d8e0 64 2c 20 61 73 20 53 51 4c 69 74 65 20 63 75 72  d, as SQLite cur
2d8f0 72 65 6e 74 6c 79 0a 2a 2a 20 64 6f 65 73 20 61  rently.** does a
2d900 6c 6c 20 70 61 72 73 69 6e 67 20 75 73 69 6e 67  ll parsing using
2d910 20 55 54 46 2d 38 2e 20 20 54 68 65 20 55 54 46   UTF-8.  The UTF
2d920 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73 20 61  -16 interfaces a
2d930 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 61  re provided.** a
2d940 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 2e  s a convenience.
2d950 20 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74    The UTF-16 int
2d960 65 72 66 61 63 65 73 20 77 6f 72 6b 20 62 79 20  erfaces work by 
2d970 63 6f 6e 76 65 72 74 69 6e 67 20 74 68 65 0a 2a  converting the.*
2d980 2a 20 69 6e 70 75 74 20 74 65 78 74 20 69 6e 74  * input text int
2d990 6f 20 55 54 46 2d 38 2c 20 74 68 65 6e 20 69 6e  o UTF-8, then in
2d9a0 76 6f 6b 69 6e 67 20 74 68 65 20 63 6f 72 72 65  voking the corre
2d9b0 73 70 6f 6e 64 69 6e 67 20 55 54 46 2d 38 20 69  sponding UTF-8 i
2d9c0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
2d9d0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2d9e0 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
2d9f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2da00 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
2da10 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75  om a.** prior su
2da20 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
2da30 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
2da40 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
2da50 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
2da60 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
2da70 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63    The database c
2da80 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
2da90 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f  ot have been clo
2daa0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
2dab0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
2dac0 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
2dad0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
2dae0 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
2daf0 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
2db00 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
2db10 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
2db20 61 72 65 28 29 2c 20 73 71 6c 69 74 65 33 5f 70  are(), sqlite3_p
2db30 72 65 70 61 72 65 5f 76 32 28 29 2c 0a 2a 2a 20  repare_v2(),.** 
2db40 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
2db50 61 72 65 5f 76 33 28 29 0a 2a 2a 20 69 6e 74 65  are_v3().** inte
2db60 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
2db70 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
2db80 65 70 61 72 65 31 36 28 29 2c 20 73 71 6c 69 74  epare16(), sqlit
2db90 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2dba0 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ),.** and sqlite
2dbb0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2dbc0 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a   use UTF-16..**.
2dbd0 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65  ** ^If the nByte
2dbe0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67   argument is neg
2dbf0 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c  ative, then zSql
2dc00 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
2dc10 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
2dc20 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66   terminator. ^If
2dc30 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74 69   nByte is positi
2dc40 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
2dc50 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2dc60 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20  bytes read from 
2dc70 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65  zSql.  ^If nByte
2dc80 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e   is zero, then n
2dc90 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  o prepared.** st
2dca0 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72  atement is gener
2dcb0 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ated..** If the 
2dcc0 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61  caller knows tha
2dcd0 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
2dce0 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
2dcf0 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a  minated, then.**
2dd00 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
2dd10 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  l performance ad
2dd20 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69  vantage to passi
2dd30 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
2dd40 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
2dd50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2dd60 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
2dd70 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
2dd80 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65  uding</i>.** the
2dd90 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e   nul-terminator.
2dda0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69  .**.** ^If pzTai
2ddb0 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  l is not NULL th
2ddc0 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
2ddd0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
2dde0 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a  he first byte.**
2ddf0 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
2de00 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
2de10 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
2de20 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
2de30 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c  s only.** compil
2de40 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74  e the first stat
2de50 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
2de60 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
2de70 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a  t pointing to.**
2de80 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e   what remains un
2de90 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
2dea0 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74  ^*ppStmt is left
2deb0 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
2dec0 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
2ded0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2dee0 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
2def0 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
2df00 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49  te3_step()].  ^I
2df10 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
2df20 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
2df30 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
2df40 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74   ^If the input t
2df50 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ext contains no 
2df60 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
2df70 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a  t is an empty.**
2df80 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d   string or a com
2df90 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74  ment) then *ppSt
2dfa0 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c  mt is set to NUL
2dfb0 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e  L..** The callin
2dfc0 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
2dfd0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
2dfe0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
2dff0 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
2e000 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
2e010 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2e020 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
2e030 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
2e040 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f  ** ppStmt may no
2e050 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  t be NULL..**.**
2e060 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68   ^On success, th
2e070 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
2e080 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f  e() family of ro
2e090 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
2e0a0 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74  QLITE_OK];.** ot
2e0b0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
2e0c0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
2e0d0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
2e0e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2e0f0 32 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65  2(), sqlite3_pre
2e100 70 61 72 65 5f 76 33 28 29 2c 20 73 71 6c 69 74  pare_v3(), sqlit
2e110 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2e120 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ),.** and sqlite
2e130 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2e140 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
2e150 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
2e160 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
2e170 2e 0a 2a 2a 20 54 68 65 20 6f 6c 64 65 72 20 69  ..** The older i
2e180 6e 74 65 72 66 61 63 65 73 20 28 73 71 6c 69 74  nterfaces (sqlit
2e190 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
2e1a0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2e1b0 31 36 28 29 29 0a 2a 2a 20 61 72 65 20 72 65 74  16()).** are ret
2e1c0 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61  ained for backwa
2e1d0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
2e1e0 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65  y, but their use
2e1f0 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e   is discouraged.
2e200 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 58 22  .** ^In the "vX"
2e210 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
2e220 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2e230 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72  ent.** that is r
2e240 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71  eturned (the [sq
2e250 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
2e260 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63  ct) contains a c
2e270 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72  opy of the.** or
2e280 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
2e290 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
2e2a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2e2b0 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
2e2c0 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65  * behave differe
2e2d0 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61  ntly in three wa
2e2e0 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
2e2f0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
2e300 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
2e310 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
2e320 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
2e330 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
2e340 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
2e350 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
2e360 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
2e370 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2e380 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
2e390 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
2e3a0 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
2e3b0 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20   again. As many 
2e3c0 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53  as [SQLITE_MAX_S
2e3d0 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20  CHEMA_RETRY].** 
2e3e0 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63  retries will occ
2e3f0 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  ur before sqlite
2e400 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75  3_step() gives u
2e410 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e  p and returns an
2e420 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e   error..** </li>
2e430 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
2e440 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
2e450 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73  curs, [sqlite3_s
2e460 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  tep()] will retu
2e470 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65  rn one of the de
2e480 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72  tailed.** [error
2e490 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65   codes] or [exte
2e4a0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
2e4b0 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20  ].  ^The legacy 
2e4c0 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
2e4d0 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  t.** [sqlite3_st
2e4e0 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79  ep()] would only
2e4f0 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69   return a generi
2e500 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  c [SQLITE_ERROR]
2e510 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20   result code.** 
2e520 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
2e530 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74  ion would have t
2e540 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20  o make a second 
2e550 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2e560 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20  _reset()].** in 
2e570 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68  order to find th
2e580 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75  e underlying cau
2e590 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65  se of the proble
2e5a0 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22  m. With the "v2"
2e5b0 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65   prepare.** inte
2e5c0 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65  rfaces, the unde
2e5d0 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f  rlying reason fo
2e5e0 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72  r the error is r
2e5f0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
2e600 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ely..** </li>.**
2e610 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
2e620 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  the specific val
2e630 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72  ue bound to [par
2e640 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61  ameter | host pa
2e650 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
2e660 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65  .** WHERE clause
2e670 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
2e680 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71   the choice of q
2e690 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20  uery plan for a 
2e6a0 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68  statement,.** th
2e6b0 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
2e6c0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
2e6d0 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
2e6e0 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68  d, as if there h
2e6f0 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63  ad been .** a sc
2e700 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20  hema change, on 
2e710 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69  the first  [sqli
2e720 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
2e730 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63   following any c
2e740 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20  hange.** to the 
2e750 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
2e760 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  xt | bindings] o
2e770 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65  f that [paramete
2e780 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65  r]. .** ^The spe
2e790 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57  cific value of W
2e7a0 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72  HERE-clause [par
2e7b0 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e  ameter] might in
2e7c0 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20  fluence the .** 
2e7d0 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
2e7e0 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61  plan if the para
2e7f0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66  meter is the lef
2e800 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61  t-hand side of a
2e810 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47   [LIKE].** or [G
2e820 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72  LOB] operator or
2e830 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2e840 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f  r is compared to
2e850 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75   an indexed colu
2e860 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53  mn.** and the [S
2e870 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41  QLITE_ENABLE_STA
2e880 54 34 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  T4] compile-time
2e890 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c   option is enabl
2e8a0 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  ed..** </li>.** 
2e8b0 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e 5e  </ol>.**.** <p>^
2e8c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2e8d0 76 33 28 29 20 64 69 66 66 65 72 73 20 66 72 6f  v3() differs fro
2e8e0 6d 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  m sqlite3_prepar
2e8f0 65 5f 76 32 28 29 20 6f 6e 6c 79 20 69 6e 20 68  e_v2() only in h
2e900 61 76 69 6e 67 0a 2a 2a 20 74 68 65 20 65 78 74  aving.** the ext
2e910 72 61 20 70 72 65 70 46 6c 61 67 73 20 70 61 72  ra prepFlags par
2e920 61 6d 65 74 65 72 2c 20 77 68 69 63 68 20 69 73  ameter, which is
2e930 20 61 20 62 69 74 20 61 72 72 61 79 20 63 6f 6e   a bit array con
2e940 73 69 73 74 69 6e 67 20 6f 66 20 7a 65 72 6f 20  sisting of zero 
2e950 6f 72 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68  or.** more of th
2e960 65 20 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52  e [SQLITE_PREPAR
2e970 45 5f 50 45 52 53 49 53 54 45 4e 54 7c 53 51 4c  E_PERSISTENT|SQL
2e980 49 54 45 5f 50 52 45 50 41 52 45 5f 2a 5d 20 66  ITE_PREPARE_*] f
2e990 6c 61 67 73 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  lags.  ^The.** s
2e9a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2e9b0 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
2e9c0 72 6b 73 20 65 78 61 63 74 6c 79 20 74 68 65 20  rks exactly the 
2e9d0 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74  same as.** sqlit
2e9e0 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 20  e3_prepare_v3() 
2e9f0 77 69 74 68 20 61 20 7a 65 72 6f 20 70 72 65 70  with a zero prep
2ea00 46 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 2e  Flags parameter.
2ea10 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2ea20 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
2ea30 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2ea40 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2ea50 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2ea60 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
2ea70 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2ea80 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
2ea90 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2eaa0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2eab0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2eac0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2ead0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2eae0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2eaf0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2eb00 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2eb10 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
2eb20 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2eb30 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2eb40 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2eb50 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
2eb60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
2eb70 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2eb80 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2eb90 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2eba0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
2ebb0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2ebc0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
2ebd0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2ebe0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2ebf0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2ec00 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2ec10 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
2ec20 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2ec30 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2ec40 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2ec50 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2ec60 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2ec70 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2ec80 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2ec90 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2eca0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2ecb0 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v3(.  sqlite3 *
2ecc0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2ecd0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2ece0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2ecf0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
2ed00 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2ed10 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
2ed20 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2ed30 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2ed40 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2ed50 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2ed60 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 6e  */.  unsigned in
2ed70 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20  t prepFlags, /* 
2ed80 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c  Zero or more SQL
2ed90 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c 61  ITE_PREPARE_ fla
2eda0 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  gs */.  sqlite3_
2edb0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2edc0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2edd0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2ede0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
2edf0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2ee00 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2ee10 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2ee20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
2ee30 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
2ee40 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2ee50 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2ee60 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2ee70 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
2ee80 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2ee90 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
2eea0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2eeb0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2eec0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2eed0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2eee0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2eef0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2ef00 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2ef10 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2ef20 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2ef30 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2ef40 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2ef50 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2ef60 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
2ef70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2ef80 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
2ef90 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2efa0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2efb0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2efc0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
2efd0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2efe0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
2eff0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2f000 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2f010 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2f020 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2f030 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2f040 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2f050 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2f060 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2f070 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
2f080 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2f090 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2f0a0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2f0b0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2f0c0 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 0a 20  _prepare16_v3(. 
2f0d0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2f0e0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2f0f0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2f100 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
2f110 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2f120 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
2f130 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
2f140 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2f150 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2f160 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2f170 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2f180 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65  unsigned int pre
2f190 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20  pFlags, /* Zero 
2f1a0 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50  or more SQLITE_P
2f1b0 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f  REPARE_ flags */
2f1c0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2f1d0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2f1e0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2f1f0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2f200 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
2f210 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2f220 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2f230 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2f240 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f250 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
2f260 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45  tement SQL.** ME
2f270 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2f280 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
2f290 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74  lite3_sql(P) int
2f2a0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2f2b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f   pointer to a co
2f2c0 70 79 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a  py of the UTF-8.
2f2d0 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
2f2e0 20 74 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70   to create [prep
2f2f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2f300 50 20 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72  P if P was.** cr
2f310 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eated by [sqlite
2f320 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2f330 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2f340 65 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v3()],.** [sql
2f350 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2f360 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  2()], or [sqlite
2f370 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2f380 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
2f390 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2f3a0 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2f3b0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2f3c0 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  o a UTF-8.** str
2f3d0 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
2f3e0 68 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70  he SQL text of p
2f3f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f400 74 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75  t P with.** [bou
2f410 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65  nd parameters] e
2f420 78 70 61 6e 64 65 64 2e 0a 2a 2a 20 5e 54 68 65  xpanded..** ^The
2f430 20 73 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69   sqlite3_normali
2f440 7a 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72  zed_sql(P) inter
2f450 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2f460 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d  ointer to a UTF-
2f470 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  8.** string cont
2f480 61 69 6e 69 6e 67 20 74 68 65 20 6e 6f 72 6d 61  aining the norma
2f490 6c 69 7a 65 64 20 53 51 4c 20 74 65 78 74 20 6f  lized SQL text o
2f4a0 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  f prepared state
2f4b0 6d 65 6e 74 20 50 2e 20 20 54 68 65 0a 2a 2a 20  ment P.  The.** 
2f4c0 73 65 6d 61 6e 74 69 63 73 20 75 73 65 64 20 74  semantics used t
2f4d0 6f 20 6e 6f 72 6d 61 6c 69 7a 65 20 61 20 53 51  o normalize a SQ
2f4e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20  L statement are 
2f4f0 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20  unspecified and 
2f500 73 75 62 6a 65 63 74 0a 2a 2a 20 74 6f 20 63 68  subject.** to ch
2f510 61 6e 67 65 2e 20 20 41 74 20 61 20 6d 69 6e 69  ange.  At a mini
2f520 6d 75 6d 2c 20 6c 69 74 65 72 61 6c 20 76 61 6c  mum, literal val
2f530 75 65 73 20 77 69 6c 6c 20 62 65 20 72 65 70 6c  ues will be repl
2f540 61 63 65 64 20 77 69 74 68 20 73 75 69 74 61 62  aced with suitab
2f550 6c 65 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  le.** placeholde
2f560 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  rs..**.** ^(For 
2f570 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 20 70 72  example, if a pr
2f580 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f590 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e   is created usin
2f5a0 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65 78  g the SQL.** tex
2f5b0 74 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a  t "SELECT $abc,:
2f5c0 78 79 7a 22 20 61 6e 64 20 69 66 20 70 61 72 61  xyz" and if para
2f5d0 6d 65 74 65 72 20 24 61 62 63 20 69 73 20 62 6f  meter $abc is bo
2f5e0 75 6e 64 20 74 6f 20 69 6e 74 65 67 65 72 20 32  und to integer 2
2f5f0 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61 6d  345.** and param
2f600 65 74 65 72 20 3a 78 79 7a 20 69 73 20 75 6e 62  eter :xyz is unb
2f610 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69 74  ound, then sqlit
2f620 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72 65  e3_sql() will re
2f630 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69 67  turn.** the orig
2f640 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20 22 53 45  inal string, "SE
2f650 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20  LECT $abc,:xyz" 
2f660 62 75 74 20 73 71 6c 69 74 65 33 5f 65 78 70 61  but sqlite3_expa
2f670 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77 69  nded_sql().** wi
2f680 6c 6c 20 72 65 74 75 72 6e 20 22 53 45 4c 45 43  ll return "SELEC
2f690 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a  T 2345,NULL".)^.
2f6a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2f6b0 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2f6c0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2f6d0 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75  rns NULL if insu
2f6e0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 0a  fficient memory.
2f6f0 2a 2a 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  ** is available 
2f700 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
2f710 6c 74 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65  lt, or if the re
2f720 73 75 6c 74 20 77 6f 75 6c 64 20 65 78 63 65 65  sult would excee
2f730 64 20 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61 78  d the.** the max
2f740 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e 67  imum string leng
2f750 74 68 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  th determined by
2f760 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49 4d   the [SQLITE_LIM
2f770 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a  IT_LENGTH]..**.*
2f780 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 54  * ^The [SQLITE_T
2f790 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d  RACE_SIZE_LIMIT]
2f7a0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2f7b0 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65 20  tion limits the 
2f7c0 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64  size of.** bound
2f7d0 20 70 61 72 61 6d 65 74 65 72 20 65 78 70 61 6e   parameter expan
2f7e0 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53 51  sions.  ^The [SQ
2f7f0 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45 5d  LITE_OMIT_TRACE]
2f800 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
2f810 20 6f 70 74 69 6f 6e 20 63 61 75 73 65 73 20 73   option causes s
2f820 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2f830 73 71 6c 28 29 20 74 6f 20 61 6c 77 61 79 73 20  sql() to always 
2f840 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a  return NULL..**.
2f850 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 73 20  ** ^The strings 
2f860 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2f870 74 65 33 5f 73 71 6c 28 50 29 20 61 6e 64 20 73  te3_sql(P) and s
2f880 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a 65  qlite3_normalize
2f890 64 5f 73 71 6c 28 50 29 0a 2a 2a 20 61 72 65 20  d_sql(P).** are 
2f8a0 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c 69 74  managed by SQLit
2f8b0 65 20 61 6e 64 20 61 72 65 20 61 75 74 6f 6d 61  e and are automa
2f8c0 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20 77 68  tically freed wh
2f8d0 65 6e 20 74 68 65 20 70 72 65 70 61 72 65 64 0a  en the prepared.
2f8e0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ** statement is 
2f8f0 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54  finalized..** ^T
2f900 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e  he string return
2f910 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65 78  ed by sqlite3_ex
2f920 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f  panded_sql(P), o
2f930 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64  n the other hand
2f940 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 64  ,.** is obtained
2f950 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2f960 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73  alloc()] and mus
2f970 74 20 62 65 20 66 72 65 65 20 62 79 20 74 68 65  t be free by the
2f980 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
2f990 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  by passing it to
2f9a0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
2f9b0 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
2f9c0 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71   *sqlite3_sql(sq
2f9d0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2f9e0 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
2f9f0 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73  3_expanded_sql(s
2fa00 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2fa10 6d 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  mt);.const char 
2fa20 2a 73 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69  *sqlite3_normali
2fa30 7a 65 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  zed_sql(sqlite3_
2fa40 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2fa50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2fa60 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
2fa70 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69  QL Statement Wri
2fa80 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65  tes The Database
2fa90 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2faa0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2fab0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2fac0 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74  _readonly(X) int
2fad0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2fae0 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
2faf0 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66  f.** and only if
2fb00 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2fb10 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65  tatement] X make
2fb20 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e  s no direct chan
2fb30 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f  ges to.** the co
2fb40 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
2fb50 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  abase file..**.*
2fb60 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70  * Note that [app
2fb70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2fb80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
2fb90 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74  or.** [virtual t
2fba0 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61  ables] might cha
2fbb0 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
2fbc0 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61   indirectly as a
2fbd0 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a   side effect.  .
2fbe0 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
2fbf0 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  , if an applicat
2fc00 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75  ion defines a fu
2fc10 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20  nction "eval()" 
2fc20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b  that .** calls [
2fc30 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
2fc40 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77   then the follow
2fc50 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
2fc60 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67  t would.** chang
2fc70 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
2fc80 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65  ile through side
2fc90 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20  -effects:.**.** 
2fca0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
2fcb0 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65  >.**    SELECT e
2fcc0 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d  val('DELETE FROM
2fcd0 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a   t1') FROM t2;.*
2fce0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
2fcf0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20  uote>.**.** But 
2fd00 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c  because the [SEL
2fd10 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64  ECT] statement d
2fd20 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
2fd30 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2fd40 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71  .** directly, sq
2fd50 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2fd60 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c  nly() would stil
2fd70 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e  l return true.)^
2fd80 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74  .**.** ^Transact
2fd90 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74  ion control stat
2fda0 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b  ements such as [
2fdb0 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d  BEGIN], [COMMIT]
2fdc0 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a  , [ROLLBACK],.**
2fdd0 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e   [SAVEPOINT], an
2fde0 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73  d [RELEASE] caus
2fdf0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
2fe00 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
2fe10 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e  urn true,.** sin
2fe20 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ce the statement
2fe30 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20  s themselves do 
2fe40 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64  not actually mod
2fe50 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
2fe60 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74   but.** rather t
2fe70 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20  hey control the 
2fe80 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f  timing of when o
2fe90 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20  ther statements 
2fea0 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64  modify the .** d
2feb0 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b  atabase.  ^The [
2fec0 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54  ATTACH] and [DET
2fed0 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ACH] statements 
2fee0 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71  also cause.** sq
2fef0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2ff00 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
2ff10 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c  true since, whil
2ff20 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e  e those statemen
2ff30 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ts.** change the
2ff40 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
2ff50 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  f a database con
2ff60 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f  nection, they do
2ff70 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68   not make .** ch
2ff80 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e  anges to the con
2ff90 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
2ffa0 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69  base files on di
2ffb0 73 6b 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  sk..** ^The sqli
2ffc0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2ffd0 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  y() interface re
2ffe0 74 75 72 6e 73 20 74 72 75 65 20 66 6f 72 20 5b  turns true for [
2fff0 42 45 47 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20  BEGIN] since.** 
30000 5b 42 45 47 49 4e 5d 20 6d 65 72 65 6c 79 20 73  [BEGIN] merely s
30010 65 74 73 20 69 6e 74 65 72 6e 61 6c 20 66 6c 61  ets internal fla
30020 67 73 2c 20 62 75 74 20 74 68 65 20 5b 42 45 47  gs, but the [BEG
30030 49 4e 7c 42 45 47 49 4e 20 49 4d 4d 45 44 49 41  IN|BEGIN IMMEDIA
30040 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49  TE] and.** [BEGI
30050 4e 7c 42 45 47 49 4e 20 45 58 43 4c 55 53 49 56  N|BEGIN EXCLUSIV
30060 45 5d 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 20 74  E] commands do t
30070 6f 75 63 68 20 74 68 65 20 64 61 74 61 62 61 73  ouch the databas
30080 65 20 61 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c 69  e and so.** sqli
30090 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
300a0 79 28 29 20 72 65 74 75 72 6e 73 20 66 61 6c 73  y() returns fals
300b0 65 20 66 6f 72 20 74 68 6f 73 65 20 63 6f 6d 6d  e for those comm
300c0 61 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ands..*/.int sql
300d0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
300e0 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ly(sqlite3_stmt 
300f0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
30100 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
30110 54 68 65 20 45 58 50 4c 41 49 4e 20 53 65 74 74  The EXPLAIN Sett
30120 69 6e 67 20 46 6f 72 20 41 20 50 72 65 70 61 72  ing For A Prepar
30130 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed Statement.** 
30140 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
30150 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
30160 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 69 73 65  sqlite3_stmt_ise
30170 78 70 6c 61 69 6e 28 53 29 20 69 6e 74 65 72 66  xplain(S) interf
30180 61 63 65 20 72 65 74 75 72 6e 73 20 31 20 69 66  ace returns 1 if
30190 20 74 68 65 0a 2a 2a 20 70 72 65 70 61 72 65 64   the.** prepared
301a0 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20   statement S is 
301b0 61 6e 20 45 58 50 4c 41 49 4e 20 73 74 61 74 65  an EXPLAIN state
301c0 6d 65 6e 74 2c 20 6f 72 20 32 20 69 66 20 74 68  ment, or 2 if th
301d0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 53  e.** statement S
301e0 20 69 73 20 61 6e 20 45 58 50 4c 41 49 4e 20 51   is an EXPLAIN Q
301f0 55 45 52 59 20 50 4c 41 4e 2e 0a 2a 2a 20 5e 54  UERY PLAN..** ^T
30200 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
30210 69 73 65 78 70 6c 61 69 6e 28 53 29 20 69 6e 74  isexplain(S) int
30220 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 30  erface returns 0
30230 20 69 66 20 53 20 69 73 0a 2a 2a 20 61 6e 20 6f   if S is.** an o
30240 72 64 69 6e 61 72 79 20 73 74 61 74 65 6d 65 6e  rdinary statemen
30250 74 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t or a NULL poin
30260 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ter..*/.int sqli
30270 74 65 33 5f 73 74 6d 74 5f 69 73 65 78 70 6c 61  te3_stmt_isexpla
30280 69 6e 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  in(sqlite3_stmt 
30290 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
302a0 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
302b0 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65  ine If A Prepare
302c0 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20  d Statement Has 
302d0 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45  Been Reset.** ME
302e0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
302f0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
30300 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
30310 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  S) interface ret
30320 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
30330 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b  ero) if the.** [
30340 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30350 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73  nt] S has been s
30360 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20  tepped at least 
30370 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  once using .** [
30380 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
30390 20 62 75 74 20 68 61 73 20 6e 65 69 74 68 65 72   but has neither
303a0 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69   run to completi
303b0 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20  on (returned.** 
303c0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72  [SQLITE_DONE] fr
303d0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  om [sqlite3_step
303e0 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65  (S)]) nor.** bee
303f0 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73  n reset using [s
30400 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
30410 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
30420 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20  stmt_busy(S).** 
30430 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
30440 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20  s false if S is 
30450 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
30460 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a   If S is not a .
30470 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
30480 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69  and is not a poi
30490 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20  nter to a valid 
304a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
304b0 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20  ent].** object, 
304c0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
304d0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  r is undefined a
304e0 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
304f0 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54  sirable..**.** T
30500 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
30510 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d  n be used in com
30520 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65  bination [sqlite
30530 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a  3_next_stmt()].*
30540 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20  * to locate all 
30550 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30560 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  nts associated w
30570 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a  ith a database .
30580 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
30590 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f  at are in need o
305a0 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20  f being reset.  
305b0 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64  This can be used
305c0 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65  ,.** for example
305d0 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20  , in diagnostic 
305e0 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72  routines to sear
305f0 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20  ch for prepared 
30600 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74  .** statements t
30610 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20  hat are holding 
30620 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70  a transaction op
30630 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  en..*/.int sqlit
30640 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c  e3_stmt_busy(sql
30650 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
30660 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79  .** CAPI3REF: Dy
30670 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20  namically Typed 
30680 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  Value Object.** 
30690 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65  KEYWORDS: {prote
306a0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
306b0 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64  ue} {unprotected
306c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a   sqlite3_value}.
306d0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
306e0 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61  s the sqlite3_va
306f0 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65  lue object to re
30700 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75  present all valu
30710 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  es.** that can b
30720 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61  e stored in a da
30730 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51  tabase table. SQ
30740 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
30750 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20  c typing.** for 
30760 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74  the values it st
30770 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73  ores.  ^Values s
30780 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33  tored in sqlite3
30790 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a  _value objects.*
307a0 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72  * can be integer
307b0 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
307c0 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
307d0 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
307e0 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69  L..**.** An sqli
307f0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
30800 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22   may be either "
30810 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75  protected" or "u
30820 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20  nprotected"..** 
30830 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  Some interfaces 
30840 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63  require a protec
30850 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
30860 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66  e.  Other interf
30870 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63  aces.** will acc
30880 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f  ept either a pro
30890 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70  tected or an unp
308a0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
308b0 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79  _value..** Every
308c0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
308d0 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f  accepts sqlite3_
308e0 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20  value arguments 
308f0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65  specifies.** whe
30900 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72  ther or not it r
30910 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63  equires a protec
30920 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
30930 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
30940 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d  te3_value_dup()]
30950 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
30960 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 72  e used to constr
30970 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72  uct a new .** pr
30980 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30990 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e  value from an un
309a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
309b0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  3_value..**.** T
309c0 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63  he terms "protec
309d0 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74  ted" and "unprot
309e0 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20  ected" refer to 
309f0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a  whether or not.*
30a00 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c  * a mutex is hel
30a10 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20  d.  An internal 
30a20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
30a30 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a  r a protected.**
30a40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
30a50 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74  bject but no mut
30a60 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
30a70 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  n unprotected.**
30a80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
30a90 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74  bject.  If SQLit
30aa0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f  e is compiled to
30ab0 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61   be single-threa
30ac0 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51  ded.** (with [SQ
30ad0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
30ae0 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c  0] and with [sql
30af0 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
30b00 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a  )] returning 0).
30b10 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20  ** or if SQLite 
30b20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66  is run in one of
30b30 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d   reduced mutex m
30b40 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  odes .** [SQLITE
30b50 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
30b60 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
30b70 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
30b80 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  EAD].** then the
30b90 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
30ba0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
30bb0 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
30bc0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
30bd0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
30be0 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20  and they can be 
30bf0 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65  used interchange
30c00 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a  ably.  However,.
30c10 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  ** for maximum c
30c20 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
30c30 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
30c40 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
30c50 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b  ons.** still mak
30c60 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
30c70 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
30c80 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
30c90 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
30ca0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65  alue objects eve
30cb0 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63  n when not stric
30cc0 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  tly required..**
30cd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30ce0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74  _value objects t
30cf0 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61  hat are passed a
30d00 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74  s parameters int
30d10 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  o the.** impleme
30d20 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c  ntation of [appl
30d30 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
30d40 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61  SQL functions] a
30d50 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a  re protected..**
30d60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
30d70 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  lue object retur
30d80 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
30d90 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
30da0 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65  )] is unprotecte
30db0 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65  d..** Unprotecte
30dc0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
30dd0 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79  objects may only
30de0 20 62 65 20 75 73 65 64 20 61 73 20 61 72 67 75   be used as argu
30df0 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c  ments.** to [sql
30e00 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
30e10 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 62  e()], [sqlite3_b
30e20 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2c 20 61 6e  ind_value()], an
30e30 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  d.** [sqlite3_va
30e40 6c 75 65 5f 64 75 70 28 29 5d 2e 0a 2a 2a 20 54  lue_dup()]..** T
30e50 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
30e60 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
30e70 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
30e80 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
30e90 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
30ea0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
30eb0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
30ec0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
30ed0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  t sqlite3_value 
30ee0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
30ef0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30f00 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
30f10 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  text Object.**.*
30f20 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
30f30 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
30f40 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
30f50 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
30f60 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
30f70 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70  xt object.  ^A p
30f80 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
30f90 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
30fa0 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
30fb0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
30fc0 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
30fd0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
30fe0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
30ff0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
31000 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
31010 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
31020 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
31030 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
31040 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
31050 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
31060 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
31070 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
31080 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
31090 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
310a0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
310b0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
310c0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
310d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
310e0 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
310f0 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
31100 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
31110 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
31120 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
31130 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
31140 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
31150 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
31160 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
31170 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59  tatements.** KEY
31180 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72  WORDS: {host par
31190 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61  ameter} {host pa
311a0 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20  rameters} {host 
311b0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a  parameter name}.
311c0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
311d0 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51  L parameter} {SQ
311e0 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70  L parameters} {p
311f0 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
31200 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
31210 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
31220 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61  ^(In the SQL sta
31230 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75  tement text inpu
31240 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
31250 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
31260 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
31270 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
31280 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
31290 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20  parameter] that 
312a0 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66  matches one of f
312b0 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70  ollowing.** temp
312c0 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  lates:.**.** <ul
312d0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
312e0 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
312f0 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
31300 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
31310 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
31320 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c  .** In the templ
31330 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20  ates above, NNN 
31340 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e  represents an in
31350 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
31360 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73  * and VVV repres
31370 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  ents an alphanum
31380 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e  eric identifier.
31390 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  )^  ^The values 
313a0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
313b0 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
313c0 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
313d0 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
313e0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
313f0 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
31400 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
31410 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
31420 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
31430 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
31440 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
31450 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
31460 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
31470 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
31480 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
31490 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
314a0 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
314b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
314c0 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
314d0 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  riants..**.** ^T
314e0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
314f0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
31500 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
31510 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
31520 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  ** ^The leftmost
31530 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
31540 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
31550 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d  .  ^When the sam
31560 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
31570 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
31580 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
31590 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
315a0 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
315b0 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
315c0 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
315d0 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
315e0 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78  e..** ^The index
315f0 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
31600 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
31610 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
31620 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
31630 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
31640 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
31650 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78  red.  ^The index
31660 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
31670 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
31680 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
31690 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  * ^The NNN value
316a0 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
316b0 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
316c0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
316d0 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
316e0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
316f0 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
31700 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
31710 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
31720 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
31730 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
31740 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
31750 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  ** ^If the third
31760 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
31770 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
31780 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
31790 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72  d_text16().** or
317a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
317b0 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ob() is a NULL p
317c0 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
317d0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
317e0 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61  .** is ignored a
317f0 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c  nd the end resul
31800 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  t is the same as
31810 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
31820 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ll()..**.** ^(In
31830 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
31840 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
31850 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
31860 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
31870 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
31880 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
31890 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
318a0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
318b0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
318c0 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
318d0 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
318e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
318f0 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66  acters.)^.** ^If
31900 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
31910 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
31920 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20  _bind_text() or 
31930 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
31940 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61  t16().** is nega
31950 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c  tive, then the l
31960 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
31970 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
31980 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
31990 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
319a0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
319b0 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  * If the fourth 
319c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
319d0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
319e0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
319f0 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69  en.** the behavi
31a00 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
31a10 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67  .** If a non-neg
31a20 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72  ative fourth par
31a30 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64  ameter is provid
31a40 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ed to sqlite3_bi
31a50 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20  nd_text().** or 
31a60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
31a70 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33  t16() or sqlite3
31a80 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74  _bind_text64() t
31a90 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61  hen.** that para
31aa0 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68  meter must be th
31ab0 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a  e byte offset.**
31ac0 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74   where the NUL t
31ad0 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20  erminator would 
31ae0 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74  occur assuming t
31af0 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e  he string were N
31b00 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64  UL.** terminated
31b10 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
31b20 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61  aracters occur a
31b30 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c  t byte offsets l
31b40 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65  ess than .** the
31b50 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f   value of the fo
31b60 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
31b70 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e  hen the resultin
31b80 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77  g string value w
31b90 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65  ill.** contain e
31ba0 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54  mbedded NULs.  T
31bb0 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70  he result of exp
31bc0 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69  ressions involvi
31bd0 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69  ng strings.** wi
31be0 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  th embedded NULs
31bf0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
31c00 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
31c10 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
31c20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20  BLOB and string 
31c30 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63  binding interfac
31c40 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72  es.** is a destr
31c50 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69  uctor used to di
31c60 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
31c70 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61  B or.** string a
31c80 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20  fter SQLite has 
31c90 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
31ca0 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  .  ^The destruct
31cb0 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20  or is called.** 
31cc0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
31cd0 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  e BLOB or string
31ce0 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c   even if the cal
31cf0 6c 20 74 6f 20 74 68 65 20 62 69 6e 64 20 41 50  l to the bind AP
31d00 49 20 66 61 69 6c 73 2c 0a 2a 2a 20 65 78 63 65  I fails,.** exce
31d10 70 74 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  pt the destructo
31d20 72 20 69 73 20 6e 6f 74 20 63 61 6c 6c 65 64 20  r is not called 
31d30 69 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  if the third par
31d40 61 6d 65 74 65 72 20 69 73 20 61 20 4e 55 4c 4c  ameter is a NULL
31d50 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 74  .** pointer or t
31d60 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
31d70 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2e  ter is negative.
31d80 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
31d90 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
31da0 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
31db0 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
31dc0 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
31dd0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
31de0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
31df0 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
31e00 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
31e10 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
31e20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
31e30 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
31e40 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
31e50 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
31e60 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
31e70 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
31e80 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
31e90 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
31ea0 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
31eb0 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
31ec0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
31ed0 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
31ee0 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 72 67  * ^The sixth arg
31ef0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
31f00 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d  _bind_text64() m
31f10 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a  ust be one of.**
31f20 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
31f30 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
31f40 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
31f50 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
31f60 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63  16LE].** to spec
31f70 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ify the encoding
31f80 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e 20   of the text in 
31f90 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
31fa0 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20  ter.  If.** the 
31fb0 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
31fc0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
31fd0 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f  ext64() is not o
31fe0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c  ne of the.** all
31ff0 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77  owed values show
32000 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74  n above, or if t
32010 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
32020 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a   is different.**
32030 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69   from the encodi
32040 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ng specified by 
32050 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65  the sixth parame
32060 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ter, then the be
32070 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64  havior.** is und
32080 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
32090 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
320a0 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
320b0 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
320c0 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
320d0 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
320e0 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
320f0 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
32100 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
32110 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
32120 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
32130 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
32140 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
32150 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
32160 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
32170 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
32180 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
32190 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
321a0 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
321b0 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
321c0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
321d0 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
321e0 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
321f0 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
32200 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
32210 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
32220 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
32230 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
32240 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
32250 6e 64 5f 70 6f 69 6e 74 65 72 28 53 2c 49 2c 50  nd_pointer(S,I,P
32260 2c 54 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 61  ,T,D) routine ca
32270 75 73 65 73 20 74 68 65 20 49 2d 74 68 20 70 61  uses the I-th pa
32280 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 5b 70  rameter in.** [p
32290 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
322a0 74 5d 20 53 20 74 6f 20 68 61 76 65 20 61 6e 20  t] S to have an 
322b0 53 51 4c 20 76 61 6c 75 65 20 6f 66 20 4e 55 4c  SQL value of NUL
322c0 4c 2c 20 62 75 74 20 74 6f 20 61 6c 73 6f 20 62  L, but to also b
322d0 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  e.** associated 
322e0 77 69 74 68 20 74 68 65 20 70 6f 69 6e 74 65 72  with the pointer
322f0 20 50 20 6f 66 20 74 79 70 65 20 54 2e 20 20 5e   P of type T.  ^
32300 44 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  D is either a NU
32310 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 0a 2a 2a  LL pointer or.**
32320 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
32330 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
32340 69 6f 6e 20 66 6f 72 20 50 2e 20 5e 53 51 4c 69  ion for P. ^SQLi
32350 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
32360 68 65 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72  he.** destructor
32370 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65   D with a single
32380 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 50 20 77   argument of P w
32390 68 65 6e 20 69 74 20 69 73 20 66 69 6e 69 73 68  hen it is finish
323a0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 50 2e 20 20  ed using.** P.  
323b0 54 68 65 20 54 20 70 61 72 61 6d 65 74 65 72 20  The T parameter 
323c0 73 68 6f 75 6c 64 20 62 65 20 61 20 73 74 61 74  should be a stat
323d0 69 63 20 73 74 72 69 6e 67 2c 20 70 72 65 66 65  ic string, prefe
323e0 72 61 62 6c 79 20 61 20 73 74 72 69 6e 67 0a 2a  rably a string.*
323f0 2a 20 6c 69 74 65 72 61 6c 2e 20 54 68 65 20 73  * literal. The s
32400 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e  qlite3_bind_poin
32410 74 65 72 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ter() routine is
32420 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20   part of the.** 
32430 5b 70 6f 69 6e 74 65 72 20 70 61 73 73 69 6e 67  [pointer passing
32440 20 69 6e 74 65 72 66 61 63 65 5d 20 61 64 64 65   interface] adde
32450 64 20 66 6f 72 20 53 51 4c 69 74 65 20 33 2e 32  d for SQLite 3.2
32460 30 2e 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  0.0..**.** ^If a
32470 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ny of the sqlite
32480 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
32490 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77  nes are called w
324a0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
324b0 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70  er.** for the [p
324c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
324d0 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65  t] or with a pre
324e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
324f0 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71  for which.** [sq
32500 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
32510 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f  s been called mo
32520 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e  re recently than
32530 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
32540 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  )],.** then the 
32550 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e  call will return
32560 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
32570 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65  .  If any sqlite
32580 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75  3_bind_().** rou
32590 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61  tine is passed a
325a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
325b0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62  ment] that has b
325c0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74  een finalized, t
325d0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20  he.** result is 
325e0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
325f0 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a  obably harmful..
32600 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20  **.** ^Bindings 
32610 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
32620 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
32630 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
32640 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61  ..** ^Unbound pa
32650 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
32660 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
32670 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
32680 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74  ite3_bind_* rout
32690 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
326a0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
326b0 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72  ss or an.** [err
326c0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74  or code] if anyt
326d0 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
326e0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f  .** ^[SQLITE_TOO
326f0 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65  BIG] might be re
32700 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69  turned if the si
32710 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f  ze of a string o
32720 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64  r BLOB.** exceed
32730 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64  s limits imposed
32740 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
32750 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
32760 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a  T_LENGTH]) or.**
32770 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e   [SQLITE_MAX_LEN
32780 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  GTH]..** ^[SQLIT
32790 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
327a0 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
327b0 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
327c0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
327d0 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d   ^[SQLITE_NOMEM]
327e0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
327f0 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
32800 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
32810 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
32820 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
32830 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
32840 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
32850 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
32860 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
32870 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
32880 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
32890 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
328a0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
328b0 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
328c0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
328d0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
328e0 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74  lob64(sqlite3_st
328f0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
32900 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75  void*, sqlite3_u
32910 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
32920 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
32930 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
32940 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
32950 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
32960 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
32970 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  le);.int sqlite3
32980 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
32990 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
329a0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
329b0 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
329c0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
329d0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69  qlite3_int64);.i
329e0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
329f0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
32a00 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  t*, int);.int sq
32a10 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
32a20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
32a30 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e  t,const char*,in
32a40 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
32a50 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
32a60 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
32a70 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
32a80 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
32a90 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
32aa0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
32ab0 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65  nd_text64(sqlite
32ac0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
32ad0 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74  nst char*, sqlit
32ae0 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20  e3_uint64,.     
32af0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32b00 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64      void(*)(void
32b10 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61  *), unsigned cha
32b20 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74  r encoding);.int
32b30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61   sqlite3_bind_va
32b40 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
32b50 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71  *, int, const sq
32b60 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
32b70 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
32b80 70 6f 69 6e 74 65 72 28 73 71 6c 69 74 65 33 5f  pointer(sqlite3_
32b90 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  stmt*, int, void
32ba0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 76  *, const char*,v
32bb0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
32bc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
32bd0 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
32be0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
32bf0 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t n);.int sqlite
32c00 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36  3_bind_zeroblob6
32c10 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
32c20 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69   int, sqlite3_ui
32c30 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt64);../*.** CA
32c40 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
32c50 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
32c60 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
32c70 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
32c80 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
32c90 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
32ca0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
32cb0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
32cc0 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
32cd0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
32ce0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
32cf0 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
32d00 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
32d10 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
32d20 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
32d30 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
32d40 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
32d50 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
32d60 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
32d70 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
32d80 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
32d90 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
32da0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e..**.** ^(This 
32db0 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
32dc0 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
32dd0 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
32de0 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
32df0 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
32e00 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
32e10 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
32e20 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
32e30 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
32e40 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
32e50 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
32e60 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f  s of the ?NNN fo
32e70 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  rm are used,.** 
32e80 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
32e90 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e  s in the list.)^
32ea0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
32eb0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
32ec0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
32ed0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
32ee0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
32ef0 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
32f00 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
32f10 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
32f20 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
32f30 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
32f40 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
32f50 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
32f60 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
32f70 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
32f80 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
32f90 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
32fa0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
32fb0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
32fc0 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
32fd0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
32fe0 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
32ff0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
33000 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
33010 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
33020 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
33030 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
33040 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
33050 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
33060 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
33070 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
33080 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
33090 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
330a0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
330b0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
330c0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
330d0 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
330e0 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
330f0 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
33100 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
33110 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
33120 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
33130 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
33140 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
33150 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
33160 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
33170 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
33180 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
33190 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
331a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
331b0 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
331c0 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
331d0 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
331e0 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
331f0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
33200 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
33210 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
33220 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
33230 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
33240 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
33250 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
33260 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
33270 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
33280 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
33290 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
332a0 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
332b0 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
332c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
332d0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
332e0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f  epare16_v2()], o
332f0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
33300 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v3()]..**.*
33310 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
33320 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
33330 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
33340 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
33350 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
33360 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
33370 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
33380 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
33390 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
333a0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
333b0 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
333c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
333d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
333e0 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
333f0 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
33400 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a   Name.** METHOD:
33410 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
33420 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
33430 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
33440 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
33450 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a  its name.  ^The.
33460 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
33470 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
33480 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
33490 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
334a0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
334b0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
334c0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e  ite3_bind()].  ^
334d0 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
334e0 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
334f0 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
33500 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70  s found.  ^The p
33510 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
33520 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
33530 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
33540 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
33550 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
33560 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
33570 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
33580 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
33590 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
335a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
335b0 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v3()]..**.** See
335c0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
335d0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
335e0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
335f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
33600 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
33610 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
33620 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
33630 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ame()]..*/.int s
33640 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
33650 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
33660 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
33670 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
33680 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33690 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
336a0 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
336b0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45   Statement.** ME
336c0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
336d0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61  mt.**.** ^Contra
336e0 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
336f0 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
33700 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
33710 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
33720 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
33730 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
33740 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
33750 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
33760 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74  * ^Use this rout
33770 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
33780 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
33790 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
337a0 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
337b0 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
337c0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
337d0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
337e0 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
337f0 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45  Result Set.** ME
33800 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
33810 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  mt.**.** ^Return
33820 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
33830 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
33840 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
33850 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
33860 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
33870 2e 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69  . ^If this routi
33880 6e 65 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ne returns 0, th
33890 61 74 20 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a  at means the .**
338a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
338b0 6d 65 6e 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f  ment] returns no
338c0 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
338d0 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
338e0 0a 2a 2a 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75  .** ^However, ju
338f0 73 74 20 62 65 63 61 75 73 65 20 74 68 69 73 20  st because this 
33900 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
33910 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65  a positive numbe
33920 72 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65  r does not.** me
33930 61 6e 20 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d  an that one or m
33940 6f 72 65 20 72 6f 77 73 20 6f 66 20 64 61 74 61  ore rows of data
33950 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65   will be returne
33960 64 2e 20 20 5e 41 20 53 45 4c 45 43 54 20 73 74  d.  ^A SELECT st
33970 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20  atement.** will 
33980 61 6c 77 61 79 73 20 68 61 76 65 20 61 20 70 6f  always have a po
33990 73 69 74 69 76 65 20 73 71 6c 69 74 65 33 5f 63  sitive sqlite3_c
339a0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75  olumn_count() bu
339b0 74 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  t depending on t
339c0 68 65 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  he.** WHERE clau
339d0 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61  se constraints a
339e0 6e 64 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e  nd the table con
339f0 74 65 6e 74 2c 20 69 74 20 6d 69 67 68 74 20 72  tent, it might r
33a00 65 74 75 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a  eturn no rows..*
33a10 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
33a20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
33a30 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
33a40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
33a50 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
33a60 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
33a70 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
33a80 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
33a90 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t Set.** METHOD:
33aa0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
33ab0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
33ac0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
33ad0 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
33ae0 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
33af0 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
33b00 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
33b10 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
33b20 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
33b30 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a  column_name().**
33b40 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
33b50 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
33b60 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
33b70 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  d UTF-8 string.*
33b80 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
33b90 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
33ba0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
33bb0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
33bc0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
33bd0 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72  tring.  ^The fir
33be0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
33bf0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
33c00 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
33c10 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
33c20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
33c30 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  nt. ^The second 
33c40 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
33c50 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
33c60 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  r.  ^The leftmos
33c70 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
33c80 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er 0..**.** ^The
33c90 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
33ca0 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
33cb0 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
33cc0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
33cd0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
33ce0 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
33cf0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
33d00 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
33d10 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
33d20 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
33d30 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
33d40 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
33d50 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
33d60 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
33d70 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
33d80 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
33d90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33da0 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
33db0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
33dc0 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
33dd0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lumn..**.** ^If 
33de0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
33df0 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
33e00 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
33e10 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
33e20 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
33e30 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
33e40 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
33e50 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
33e60 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
33e70 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
33e80 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
33e90 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
33ea0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
33eb0 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
33ec0 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
33ed0 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
33ee0 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
33ef0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
33f00 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
33f10 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
33f20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
33f30 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
33f40 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
33f50 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
33f60 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
33f70 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
33f80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
33f90 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
33fa0 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20  , int N);.const 
33fb0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
33fc0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
33fd0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
33fe0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33ff0 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
34000 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
34010 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  sult.** METHOD: 
34020 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
34030 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
34040 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
34050 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
34060 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61  the database, ta
34070 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c  ble, and.** tabl
34080 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  e column that is
34090 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61   the origin of a
340a0 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75   particular resu
340b0 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20  lt column in.** 
340c0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
340d0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  nt..** ^The name
340e0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
340f0 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
34100 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
34110 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
34120 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d   a UTF-8 or UTF-
34130 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
34140 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
34150 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
34160 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
34170 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
34180 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
34190 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
341a0 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
341b0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
341c0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
341d0 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
341e0 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
341f0 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
34200 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
34210 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
34220 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
34230 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
34240 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
34250 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
34260 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
34270 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
34280 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
34290 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
342a0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
342b0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
342c0 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
342d0 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
342e0 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
342f0 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
34300 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72  .** ^The names r
34310 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
34320 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
34330 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
34340 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
34350 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
34360 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
34370 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
34380 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69  ese interfaces i
34390 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
343a0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68  atement]..** ^Th
343b0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
343c0 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
343d0 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72   about the Nth r
343e0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74  esult column ret
343f0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  urned by.** the 
34400 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65  statement, where
34410 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
34420 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
34430 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  nt..** ^The left
34440 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  -most column is 
34450 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65  column 0 for the
34460 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
34470 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ** ^If the Nth c
34480 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
34490 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
344a0 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
344b0 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
344c0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
344d0 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
344e0 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
344f0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
34500 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72   NULL.  ^These r
34510 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
34520 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
34530 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
34540 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
34550 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73  curs.  ^Otherwis
34560 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
34570 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
34580 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
34590 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63  , table,.** or c
345a0 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
345b0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
345c0 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
345d0 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74  m..**.** ^As wit
345e0 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
345f0 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77  te APIs, those w
34600 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77  hose names end w
34610 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a  ith "16" return.
34620 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  ** UTF-16 encode
34630 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68  d strings and th
34640 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
34650 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a  s return UTF-8..
34660 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49  **.** ^These API
34670 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
34680 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
34690 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
346a0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
346b0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
346c0 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
346d0 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
346e0 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ol..**.** If two
346f0 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
34700 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
34710 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
34720 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
34730 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
34740 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
34750 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
34760 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
34770 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
34780 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
34790 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
347a0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
347b0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69  or more.** [sqli
347c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
347d0 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d  ase_name | colum
347e0 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
347f0 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68  faces].** for th
34800 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  e same [prepared
34810 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
34820 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
34830 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
34840 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
34850 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
34860 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
34870 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
34880 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
34890 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
348a0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
348b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
348c0 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
348d0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
348e0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
348f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
34900 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
34910 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
34920 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
34930 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
34940 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
34950 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
34960 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
34970 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
34980 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
34990 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
349a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
349b0 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
349c0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
349d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
349e0 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
349f0 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
34a00 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ult.** METHOD: s
34a10 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
34a20 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61  * ^(The first pa
34a30 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
34a40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
34a50 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
34a60 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
34a70 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
34a80 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
34a90 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
34aa0 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
34ab0 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
34ac0 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
34ad0 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
34ae0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
34af0 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
34b00 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
34b10 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
34b20 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
34b30 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68  .)^  ^If the Nth
34b40 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
34b50 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
34b60 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
34b70 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
34b80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
34b90 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
34ba0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
34bb0 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
34bc0 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a  F-8 encoded..**.
34bd0 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
34be0 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
34bf0 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
34c00 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
34c10 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
34c20 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
34c30 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
34c40 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
34c50 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
34c60 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
34c70 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
34c80 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
34c90 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
34ca0 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
34cb0 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
34cc0 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
34cd0 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
34ce0 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
34cf0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
34d00 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  i==0).)^.**.** ^
34d10 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
34d20 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
34d30 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62  ing.  ^So just b
34d40 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
34d50 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
34d60 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
34d70 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
34d80 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
34d90 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
34da0 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
34db0 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
34dc0 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
34dd0 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
34de0 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
34df0 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
34e00 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e  c not static.  ^
34e10 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
34e20 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
34e30 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
34e40 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
34e50 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
34e60 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
34e70 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  es..*/.const cha
34e80 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
34e90 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
34ea0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
34eb0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
34ec0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
34ed0 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
34ee0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
34ef0 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
34f00 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
34f10 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ent.** METHOD: s
34f20 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
34f30 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
34f40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
34f50 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
34f60 20 75 73 69 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a   using any of.**
34f70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
34f80 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
34f90 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c  3_prepare_v3()],
34fa0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
34fb0 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72  e16_v2()],.** or
34fc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
34fd0 65 31 36 5f 76 33 28 29 5d 20 6f 72 20 6f 6e 65  e16_v3()] or one
34fe0 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
34ff0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
35000 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
35010 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
35020 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
35030 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
35040 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
35050 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
35060 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
35070 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
35080 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
35090 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
350a0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
350b0 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
350c0 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
350d0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
350e0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
350f0 74 68 65 20 6e 65 77 65 72 20 22 76 58 22 20 69  the newer "vX" i
35100 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 5b 73 71  nterfaces.** [sq
35110 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
35120 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
35130 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
35140 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
35150 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v3()],.** [sqlit
35160 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
35170 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
35180 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
35190 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
351a0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
351b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
351c0 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
351d0 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 58 22 20  the.** new "vX" 
351e0 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
351f0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
35200 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
35210 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
35220 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
35230 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
35240 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  pported..**.** ^
35250 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
35260 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
35270 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
35280 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
35290 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
352a0 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
352b0 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
352c0 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
352d0 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e  TE_MISUSE]..** ^
352e0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
352f0 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
35300 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
35310 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
35320 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
35330 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
35340 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
35350 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
35360 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
35370 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
35380 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
35390 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
353a0 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
353b0 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
353c0 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74   its job.  ^If t
353d0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
353e0 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72  a [COMMIT].** or
353f0 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
35400 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
35410 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
35420 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
35430 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
35440 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
35450 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d  nt is not a [COM
35460 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20  MIT] and occurs 
35470 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70  within an.** exp
35480 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
35490 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
354a0 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
354b0 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
354c0 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
354d0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
354e0 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
354f0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
35500 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
35510 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
35520 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
35530 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
35540 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
35550 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
35560 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
35570 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
35580 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
35590 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
355a0 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
355b0 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
355c0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
355d0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51  **.** ^If the SQ
355e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
355f0 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
35600 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
35610 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
35620 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
35630 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
35640 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
35650 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
35660 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
35670 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
35680 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
35690 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
356a0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
356b0 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
356c0 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
356d0 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
356e0 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
356f0 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  f data..**.** ^[
35700 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
35710 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
35720 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
35730 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
35740 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
35750 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
35760 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
35770 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
35780 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
35790 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
357a0 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
357b0 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
357c0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
357d0 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c  ..** ^With the l
357e0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
357f0 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
35800 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72   error code (for
35810 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51   example,.** [SQ
35820 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
35830 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
35840 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
35850 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
35860 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
35870 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
35880 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
35890 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
358a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
358b0 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  .  ^In the "v2" 
358c0 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
358d0 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
358e0 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
358f0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
35900 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
35910 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
35920 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
35930 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
35940 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
35950 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
35960 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
35970 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
35980 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
35990 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
359a0 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
359b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
359c0 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
359d0 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
359e0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
359f0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
35a00 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
35a10 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
35a20 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
35a30 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
35a40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
35a50 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
35a60 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
35a70 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
35a80 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
35a90 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46  in time..**.** F
35aa0 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20  or all versions 
35ab0 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20  of SQLite up to 
35ac0 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e  and including 3.
35ad0 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74  6.23.1, a call t
35ae0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
35af0 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69  set()] was requi
35b00 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  red after sqlite
35b10 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65  3_step() returne
35b20 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74  d anything.** ot
35b30 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
35b40 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79  _ROW] before any
35b50 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
35b60 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c  cation of.** sql
35b70 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61  ite3_step().  Fa
35b80 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74  ilure to reset t
35b90 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
35ba0 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20  ement using .** 
35bb0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
35bc0 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  ] would result i
35bd0 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  n an [SQLITE_MIS
35be0 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d  USE] return from
35bf0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
35c00 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 5b  ().  But after [
35c10 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31  version 3.6.23.1
35c20 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32  ] ([dateof:3.6.2
35c30 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  3.1],.** sqlite3
35c40 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a  _step() began.**
35c50 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
35c60 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d  3_reset()] autom
35c70 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73  atically in this
35c80 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61   circumstance ra
35c90 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74  ther.** than ret
35ca0 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d  urning [SQLITE_M
35cb0 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73  ISUSE].  This is
35cc0 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20   not considered 
35cd0 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a  a compatibility.
35ce0 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65  ** break because
35cf0 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e   any application
35d00 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69   that ever recei
35d10 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49  ves an SQLITE_MI
35d20 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73  SUSE error.** is
35d30 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e   broken by defin
35d40 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c  ition.  The [SQL
35d50 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53  ITE_OMIT_AUTORES
35d60 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ET] compile-time
35d70 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62   option.** can b
35d80 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72  e used to restor
35d90 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
35da0 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  avior..**.** <b>
35db0 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
35dc0 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
35dd0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
35de0 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
35df0 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
35e00 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
35e10 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
35e20 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
35e30 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
35e40 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
35e50 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
35e60 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
35e70 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
35e80 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
35e90 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
35ea0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
35eb0 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
35ec0 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
35ed0 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
35ee0 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
35ef0 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
35f00 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
35f10 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
35f20 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
35f30 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
35f40 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
35f50 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
35f60 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
35f70 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
35f80 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
35f90 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
35fa0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
35fb0 5f 76 33 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v3()] or [sqlit
35fc0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
35fd0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
35fe0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
35ff0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
36000 61 72 65 31 36 5f 76 33 28 29 5d 20 69 6e 73 74  are16_v3()] inst
36010 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
36020 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
36030 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
36040 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
36050 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
36060 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
36070 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
36080 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
36090 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
360a0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
360b0 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
360c0 68 65 20 22 76 58 22 20 69 6e 74 65 72 66 61 63  he "vX" interfac
360d0 65 73 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  es is recommende
360e0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
360f0 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
36100 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
36110 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
36120 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
36130 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54  esult set.** MET
36140 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
36150 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
36160 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
36170 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
36180 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
36190 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
361a0 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77  e.** current row
361b0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
361c0 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  et of [prepared 
361d0 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
361e0 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74   ^If prepared st
361f0 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e  atement P does n
36200 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20  ot have results 
36210 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a  ready to return.
36220 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f  ** (via calls to
36230 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
36240 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74  lumn_int | sqlit
36250 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f  e3_column_*()] o
36260 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29  f.** interfaces)
36270 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61   then sqlite3_da
36280 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75  ta_count(P) retu
36290 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73  rns 0..** ^The s
362a0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
362b0 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73  t(P) routine als
362c0 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50  o returns 0 if P
362d0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
362e0 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  er..** ^The sqli
362f0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
36300 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
36310 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69  s 0 if the previ
36320 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ous call to.** [
36330 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
36340 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
36350 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73  E_DONE].  ^The s
36360 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
36370 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74  t(P).** will ret
36380 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20  urn non-zero if 
36390 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
363a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
363b0 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  P) returned.** [
363c0 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63  SQLITE_ROW], exc
363d0 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20  ept in the case 
363e0 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69  of the [PRAGMA i
363f0 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75  ncremental_vacuu
36400 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61  m].** where it a
36410 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65  lways returns ze
36420 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74  ro since each st
36430 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69  ep of that multi
36440 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20  -step.** pragma 
36450 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e  returns 0 column
36460 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  s of data..**.**
36470 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
36480 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
36490 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()].*/.int sqlit
364a0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71  e3_data_count(sq
364b0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
364c0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
364d0 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c  REF: Fundamental
364e0 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45   Datatypes.** KE
364f0 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
36500 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72  EXT.**.** ^(Ever
36510 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
36520 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
36530 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
36540 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
36550 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
36560 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
36570 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
36580 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
36590 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
365a0 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
365b0 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
365c0 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  NULL.** </ul>)^.
365d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
365e0 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
365f0 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
36600 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
36610 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
36620 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
36630 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
36640 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
36650 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
36660 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
36670 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
36680 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
36690 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
366a0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
366b0 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
366c0 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
366d0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e   SQLITE3_TEXT, n
366e0 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
366f0 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
36700 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
36710 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
36720 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
36730 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
36740 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
36750 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
36760 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
36770 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
36780 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
36790 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
367a0 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
367b0 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
367c0 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
367d0 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
367e0 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
367f0 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ery.** KEYWORDS:
36800 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   {column access 
36810 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45  functions}.** ME
36820 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
36830 6d 74 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d  mt.**.** <b>Summ
36840 61 72 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f  ary:</b>.** <blo
36850 63 6b 71 75 6f 74 65 3e 3c 74 61 62 6c 65 20 62  ckquote><table b
36860 6f 72 64 65 72 3d 30 20 63 65 6c 6c 70 61 64 64  order=0 cellpadd
36870 69 6e 67 3d 30 20 63 65 6c 6c 73 70 61 63 69 6e  ing=0 cellspacin
36880 67 3d 30 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  g=0>.** <tr><td>
36890 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
368a0 6e 5f 62 6c 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72  n_blob</b><td>&r
368b0 61 72 72 3b 3c 74 64 3e 42 4c 4f 42 20 72 65 73  arr;<td>BLOB res
368c0 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  ult.** <tr><td><
368d0 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
368e0 5f 64 6f 75 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26  _double</b><td>&
368f0 72 61 72 72 3b 3c 74 64 3e 52 45 41 4c 20 72 65  rarr;<td>REAL re
36900 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  sult.** <tr><td>
36910 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
36920 6e 5f 69 6e 74 3c 2f 62 3e 3c 74 64 3e 26 72 61  n_int</b><td>&ra
36930 72 72 3b 3c 74 64 3e 33 32 2d 62 69 74 20 49 4e  rr;<td>32-bit IN
36940 54 45 47 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20  TEGER result.** 
36950 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
36960 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c  e3_column_int64<
36970 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
36980 3e 36 34 2d 62 69 74 20 49 4e 54 45 47 45 52 20  >64-bit INTEGER 
36990 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74  result.** <tr><t
369a0 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
369b0 75 6d 6e 5f 74 65 78 74 3c 2f 62 3e 3c 74 64 3e  umn_text</b><td>
369c0 26 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d 38 20  &rarr;<td>UTF-8 
369d0 54 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c  TEXT result.** <
369e0 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
369f0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 3c  3_column_text16<
36a00 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
36a10 3e 55 54 46 2d 31 36 20 54 45 58 54 20 72 65 73  >UTF-16 TEXT res
36a20 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  ult.** <tr><td><
36a30 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
36a40 5f 76 61 6c 75 65 3c 2f 62 3e 3c 74 64 3e 26 72  _value</b><td>&r
36a50 61 72 72 3b 3c 74 64 3e 54 68 65 20 72 65 73 75  arr;<td>The resu
36a60 6c 74 20 61 73 20 61 6e 20 0a 2a 2a 20 5b 73 71  lt as an .** [sq
36a70 6c 69 74 65 33 5f 76 61 6c 75 65 7c 75 6e 70 72  lite3_value|unpr
36a80 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
36a90 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  value] object..*
36aa0 2a 20 3c 74 72 3e 3c 74 64 3e 26 6e 62 73 70 3b  * <tr><td>&nbsp;
36ab0 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e  <td>&nbsp;<td>&n
36ac0 62 73 70 3b 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  bsp;.** <tr><td>
36ad0 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
36ae0 6e 5f 62 79 74 65 73 3c 2f 62 3e 3c 74 64 3e 26  n_bytes</b><td>&
36af0 72 61 72 72 3b 3c 74 64 3e 53 69 7a 65 20 6f 66  rarr;<td>Size of
36b00 20 61 20 42 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20   a BLOB.** or a 
36b10 55 54 46 2d 38 20 54 45 58 54 20 72 65 73 75 6c  UTF-8 TEXT resul
36b20 74 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74  t in bytes.** <t
36b30 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
36b40 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 26  _column_bytes16&
36b50 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a  nbsp;&nbsp;</b>.
36b60 2a 2a 20 3c 74 64 3e 26 72 61 72 72 3b 26 6e 62  ** <td>&rarr;&nb
36b70 73 70 3b 26 6e 62 73 70 3b 3c 74 64 3e 53 69 7a  sp;&nbsp;<td>Siz
36b80 65 20 6f 66 20 55 54 46 2d 31 36 0a 2a 2a 20 54  e of UTF-16.** T
36b90 45 58 54 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20  EXT in bytes.** 
36ba0 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
36bb0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f  e3_column_type</
36bc0 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
36bd0 44 65 66 61 75 6c 74 0a 2a 2a 20 64 61 74 61 74  Default.** datat
36be0 79 70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ype of the resul
36bf0 74 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62  t.** </table></b
36c00 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
36c10 20 3c 62 3e 44 65 74 61 69 6c 73 3a 3c 2f 62 3e   <b>Details:</b>
36c20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
36c30 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
36c40 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
36c50 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
36c60 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
36c70 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
36c80 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
36c90 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
36ca0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
36cb0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
36cc0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
36cd0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
36ce0 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
36cf0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
36d00 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
36d10 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
36d20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
36d30 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
36d40 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
36d50 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
36d60 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
36d70 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
36d80 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
36d90 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
36da0 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
36db0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
36dc0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
36dd0 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
36de0 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
36df0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
36e00 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
36e10 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
36e20 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
36e30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
36e40 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
36e50 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
36e60 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
36e70 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
36e80 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
36e90 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
36ea0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
36eb0 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
36ec0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
36ed0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
36ee0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
36ef0 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
36f00 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
36f10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
36f20 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
36f30 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
36f40 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
36f50 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
36f60 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
36f70 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
36f80 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
36f90 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
36fa0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
36fb0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
36fc0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
36fd0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
36fe0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
36ff0 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
37000 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
37010 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
37020 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
37030 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
37040 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
37050 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
37060 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
37070 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
37080 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
37090 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
370a0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
370b0 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
370c0 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
370d0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
370e0 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
370f0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
37100 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
37110 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 73  *.** The first s
37120 69 78 20 69 6e 74 65 72 66 61 63 65 73 20 28 5f  ix interfaces (_
37130 62 6c 6f 62 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f  blob, _double, _
37140 69 6e 74 2c 20 5f 69 6e 74 36 34 2c 20 5f 74 65  int, _int64, _te
37150 78 74 2c 20 61 6e 64 20 5f 74 65 78 74 31 36 29  xt, and _text16)
37160 0a 2a 2a 20 65 61 63 68 20 72 65 74 75 72 6e 20  .** each return 
37170 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61 20 72  the value of a r
37180 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 20  esult column in 
37190 61 20 73 70 65 63 69 66 69 63 20 64 61 74 61 20  a specific data 
371a0 66 6f 72 6d 61 74 2e 20 20 49 66 0a 2a 2a 20 74  format.  If.** t
371b0 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
371c0 20 69 73 20 6e 6f 74 20 69 6e 69 74 69 61 6c 6c   is not initiall
371d0 79 20 69 6e 20 74 68 65 20 72 65 71 75 65 73 74  y in the request
371e0 65 64 20 66 6f 72 6d 61 74 20 28 66 6f 72 20 65  ed format (for e
371f0 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 66 20 74 68  xample,.** if th
37200 65 20 71 75 65 72 79 20 72 65 74 75 72 6e 73 20  e query returns 
37210 61 6e 20 69 6e 74 65 67 65 72 20 62 75 74 20 74  an integer but t
37220 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
37230 6e 5f 74 65 78 74 28 29 20 69 6e 74 65 72 66 61  n_text() interfa
37240 63 65 0a 2a 2a 20 69 73 20 75 73 65 64 20 74 6f  ce.** is used to
37250 20 65 78 74 72 61 63 74 20 74 68 65 20 76 61 6c   extract the val
37260 75 65 29 20 74 68 65 6e 20 61 6e 20 61 75 74 6f  ue) then an auto
37270 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e 76 65  matic type conve
37280 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
37290 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
372a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
372b0 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
372c0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
372d0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
372e0 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
372f0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
37300 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
37310 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
37320 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76   ^The returned v
37330 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
37340 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
37350 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
37360 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
37370 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
37380 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
37390 4c 5d 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  L]..** The retur
373a0 6e 20 76 61 6c 75 65 20 6f 66 20 73 71 6c 69 74  n value of sqlit
373b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
373c0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
373d0 64 65 63 69 64 65 20 77 68 69 63 68 0a 2a 2a 20  decide which.** 
373e0 6f 66 20 74 68 65 20 66 69 72 73 74 20 73 69 78  of the first six
373f0 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c   interface shoul
37400 64 20 62 65 20 75 73 65 64 20 74 6f 20 65 78 74  d be used to ext
37410 72 61 63 74 20 74 68 65 20 63 6f 6c 75 6d 6e 20  ract the column 
37420 76 61 6c 75 65 2e 0a 2a 2a 20 54 68 65 20 76 61  value..** The va
37430 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
37440 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
37450 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65  ype() is only me
37460 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 0a 2a  aningful if no.*
37470 2a 20 61 75 74 6f 6d 61 74 69 63 20 74 79 70 65  * automatic type
37480 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76   conversions hav
37490 65 20 6f 63 63 75 72 72 65 64 20 66 6f 72 20 74  e occurred for t
374a0 68 65 20 76 61 6c 75 65 20 69 6e 20 71 75 65 73  he value in ques
374b0 74 69 6f 6e 2e 20 20 0a 2a 2a 20 41 66 74 65 72  tion.  .** After
374c0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
374d0 6f 6e 2c 20 74 68 65 20 72 65 73 75 6c 74 20 6f  on, the result o
374e0 66 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  f calling sqlite
374f0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
37500 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2c  ** is undefined,
37510 20 74 68 6f 75 67 68 20 68 61 72 6d 6c 65 73 73   though harmless
37520 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
37530 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
37540 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
37550 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
37560 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
37570 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
37580 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
37590 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65  .**.** If the re
375a0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
375b0 72 20 61 20 54 45 58 54 20 73 74 72 69 6e 67 2c  r a TEXT string,
375c0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
375d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
375e0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  .** or sqlite3_c
375f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
37600 69 6e 74 65 72 66 61 63 65 73 20 63 61 6e 20 62  interfaces can b
37610 65 20 75 73 65 64 20 74 6f 20 64 65 74 65 72 6d  e used to determ
37620 69 6e 65 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20  ine the size.** 
37630 6f 66 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  of that BLOB or 
37640 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  string..**.** ^I
37650 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
37660 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
37670 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
37680 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
37690 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ytes().** routin
376a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
376b0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
376c0 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
376d0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
376e0 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
376f0 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
37700 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
37710 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
37720 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
37730 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
37740 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
37750 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
37760 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
37770 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
37780 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
37790 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
377a0 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
377b0 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
377c0 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
377d0 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
377e0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
377f0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
37800 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
37810 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
37820 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
37830 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
37840 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65  olumn_bytes() re
37850 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
37860 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
37870 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
37880 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e  F-16 string then
37890 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
378a0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a  umn_bytes16().**
378b0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
378c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
378d0 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
378e0 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
378f0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
37900 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
37910 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
37920 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
37930 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
37940 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36  string to UTF-16
37950 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
37960 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
37970 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
37980 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
37990 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
379a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
379b0 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a  bytes16() uses.*
379c0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
379d0 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
379e0 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
379f0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
37a00 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
37a10 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
37a20 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
37a30 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
37a40 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
37a50 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
37a60 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75  n_bytes16() retu
37a70 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
37a80 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
37a90 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
37aa0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
37ab0 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
37ac0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
37ad0 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75  ()] do not inclu
37ae0 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
37af0 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65  inators at the e
37b00 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
37b10 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69  ing.  ^For clari
37b20 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72  ty: the values r
37b30 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
37b40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
37b50 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tes()] and [sqli
37b60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
37b70 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75  16()] are the nu
37b80 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
37b90 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
37ba0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
37bb0 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
37bc0 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74  .** ^Strings ret
37bd0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
37be0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
37bf0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
37c00 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
37c10 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
37c20 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
37c30 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
37c40 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76  ^The return.** v
37c50 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
37c60 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
37c70 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
37c80 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c  h BLOB is a NULL
37c90 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
37ca0 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20  <b>Warning:</b> 
37cb0 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75  ^The object retu
37cc0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
37cd0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
37ce0 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
37cf0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
37d00 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49  alue] object.  I
37d10 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65  n a multithreade
37d20 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a  d environment,.*
37d30 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  * an unprotected
37d40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
37d50 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62  bject may only b
37d60 65 20 75 73 65 64 20 73 61 66 65 6c 79 20 77 69  e used safely wi
37d70 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  th.** [sqlite3_b
37d80 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
37d90 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
37da0 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
37db0 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
37dc0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
37dd0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
37de0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
37df0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
37e00 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
37e10 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
37e20 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
37e30 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
37e40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
37e50 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
37e60 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
37e70 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
37e80 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20  e_bytes()], the 
37e90 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20  behavior is not 
37ea0 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 20 48  threadsafe..** H
37eb0 65 6e 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  ence, the sqlite
37ec0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
37ed0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73   interface.** is
37ee0 20 6e 6f 72 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75   normally only u
37ef0 73 65 66 75 6c 20 77 69 74 68 69 6e 20 74 68 65  seful within the
37f00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
37f10 6f 66 20 0a 2a 2a 20 5b 61 70 70 6c 69 63 61 74  of .** [applicat
37f20 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
37f30 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 76  functions] or [v
37f40 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2c 20  irtual tables], 
37f50 6e 6f 74 20 77 69 74 68 69 6e 0a 2a 2a 20 74 6f  not within.** to
37f60 70 2d 6c 65 76 65 6c 20 61 70 70 6c 69 63 61 74  p-level applicat
37f70 69 6f 6e 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20  ion code..**.** 
37f80 54 68 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  The these routin
37f90 65 73 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74  es may attempt t
37fa0 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 64 61  o convert the da
37fb0 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 72 65  tatype of the re
37fc0 73 75 6c 74 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78  sult..** ^For ex
37fd0 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
37fe0 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
37ff0 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
38000 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
38010 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
38020 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
38030 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
38040 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
38050 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
38060 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
38070 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
38080 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
38090 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
380a0 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
380b0 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
380c0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
380d0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
380e0 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
380f0 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
38100 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
38110 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
38120 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
38130 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
38140 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
38150 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
38160 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
38170 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
38180 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
38190 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
381a0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
381b0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
381c0 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c  Result is a NULL
381d0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
381e0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
381f0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
38200 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55  > Result is a NU
38210 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
38220 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
38230 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
38240 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
38250 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
38260 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
38270 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
38280 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
38290 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
382a0 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
382b0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
382c0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
382d0 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47  d> Same as INTEG
382e0 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
382f0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
38300 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
38310 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
38320 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
38330 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
38340 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
38350 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
38360 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
38370 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
38380 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
38390 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f  d> [CAST] to BLO
383a0 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  B.** <tr><td>  T
383b0 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
383c0 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
383d0 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
383e0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
383f0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
38400 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
38410 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
38420 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
38430 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
38440 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
38450 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
38460 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
38470 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
38480 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
38490 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
384a0 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
384b0 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
384c0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
384d0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
384e0 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
384f0 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
38500 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
38510 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
38520 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  )^.**.** Note th
38530 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
38540 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
38550 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
38560 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
38570 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
38580 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
38590 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
385a0 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
385b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
385c0 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
385d0 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79  validated..** Ty
385e0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
385f0 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
38600 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
38610 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
38620 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
38630 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
38640 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
38650 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
38660 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
38670 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
38680 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
38690 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
386a0 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
386b0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
386c0 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
386d0 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
386e0 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
386f0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
38700 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
38710 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sq