/ Hex Artifact Content
Login

Artifact ac6aec2abe10585733c1fea06622df5d73f7725c36c6cf054e89affeaccfa42b:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c  ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a  ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66  .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53  _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f   file.  ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72  us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20  s might include 
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70  nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76  lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65  erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20  atch the macros 
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72  in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72  , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69  e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d  cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68  piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20  ing library and 
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a  header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28  <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51  ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65  ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30  ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c  BER].  ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20  rocessor macro. 
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74   Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73  e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f  ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67  py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74  amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61  he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68  racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20  e hash might be 
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b  different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1e00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1e10: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1e20: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1e30: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1e40: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1e50: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1e60: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1e70: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1e80: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1e90: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1ea0: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1eb0: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1ec0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1ed0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1ee0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1ef0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1f00: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1f10: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1f20: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1f30: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1f40: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1f50: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1f60: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1f70: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1f80: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1f90: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1fa0: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1fb0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1fc0: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1fd0: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1fe0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1ff0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
2000: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
2010: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
2020: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
2030: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
2040: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
2050: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
2060: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
2070: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
2080: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
2090: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
20a0: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
20b0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
20c0: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
20d0: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
20e0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
20f0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
2100: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
2110: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
2120: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
2130: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2140: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2150: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2160: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2170: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
2180: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
2190: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
21a0: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
21b0: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
21c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
21d0: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
21e0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
21f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2200: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
2210: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
2220: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
2230: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2240: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2250: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2260: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
2290: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
22a0: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
22b0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
22c0: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
22d0: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
22e0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
22f0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
2300: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
2310: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
2320: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
2330: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2340: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2350: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2360: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2370: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
2380: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
2390: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
23a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
23b0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
23c0: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
23d0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
23e0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
23f0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
2400: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
2410: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
2420: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2430: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2440: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2450: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2460: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2470: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2480: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2490: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
24a0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
24b0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
24c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
24d0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
24e0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
24f0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
2500: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2510: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
2520: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2530: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2540: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2550: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2560: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2570: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2580: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2590: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
25a0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
25b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
25c0: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
25d0: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
25e0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
25f0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
2600: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
2610: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
2620: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
2630: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2640: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2650: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2660: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2670: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2680: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2690: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
26a0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
26b0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
26c0: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
26d0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
26e0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
26f0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
2700: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
2710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2730: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2740: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2750: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2760: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2770: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2780: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2790: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
27a0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
27b0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
27c0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
27d0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
27e0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
27f0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
2800: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2810: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
2820: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
2830: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2840: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2850: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2860: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2870: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2880: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2890: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
28a0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
28b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
28c0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
28d0: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
28e0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
28f0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
2900: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
2910: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2920: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
2930: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2940: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2950: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2960: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2970: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2980: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2990: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
29a0: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
29b0: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
29c0: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
29d0: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
29e0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
29f0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
2a00: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2a10: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2a20: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
2a30: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2a40: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2a50: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2a60: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2a70: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2a80: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2a90: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2aa0: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45  ;.# ifdef SQLITE
2ab0: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20  _UINT64_TYPE.   
2ac0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2ad0: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  UINT64_TYPE sqli
2ae0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73  te_uint64;.# els
2af0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20  e  .    typedef 
2b00: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2b20: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69  e_uint64;.# endi
2b30: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  f.#elif defined(
2b40: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2b50: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2b60: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2b70: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2b80: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2b90: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2ba0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2bb0: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2bc0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2bd0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2be0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2bf0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2c00: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2c10: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2c30: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2c40: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2c50: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2c60: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2c70: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2c80: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2c90: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2ca0: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2cb0: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2cc0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2cd0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2ce0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2cf0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2d00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2d10: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2d20: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2d30: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2d40: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2d50: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2d60: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2d70: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2d80: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2d90: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2da0: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2db0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2dc0: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2dd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2de0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2df0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2e00: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2e10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2e20: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2e30: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2e40: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2e50: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2e60: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2e80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e90: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2ea0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2eb0: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2ec0: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ed0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2ee0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2ef0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2f00: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2f10: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2f20: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2f30: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2f40: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2f50: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2f60: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2f70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2f80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2f90: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2fa0: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2fb0: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2fc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fd0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2fe0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2ff0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
3000: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
3010: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
3020: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
3030: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
3040: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
3050: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
3060: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
3070: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
3080: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
3090: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
30a0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
30b0: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
30c0: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
30d0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
30e0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
30f0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
3100: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
3110: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
3120: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
3130: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3140: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3150: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
3160: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3170: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3180: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3190: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
31a0: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
31b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
31c0: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
31d0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
31e0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31f0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
3200: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
3210: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
3220: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
3230: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3240: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3250: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3260: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3270: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3280: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3290: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
32a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32b0: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
32c0: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
32d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
32e0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
32f0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
3300: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
3310: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3320: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3330: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3340: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3350: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3360: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3370: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3380: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3390: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
33a0: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
33b0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
33c0: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
33d0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
33e0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
33f0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3400: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3410: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3420: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3440: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3450: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3460: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3470: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3480: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3490: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
34a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
34b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
34c0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
34d0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
34e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
34f0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3500: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3510: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3520: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3530: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3540: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3550: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3560: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3570: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3580: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3590: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35a0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
35b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
35c0: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
35d0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
35e0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
35f0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
3600: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
3610: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
3620: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3630: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3640: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3650: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3660: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3670: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3680: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3690: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
36a0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
36b0: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
36c0: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
36d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
36e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
36f0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
3700: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
3710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
3720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
3730: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3740: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3750: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
3760: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
3770: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
3780: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
3790: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
37a0: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
37b0: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
37c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
37e0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
37f0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
3800: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
3810: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
3820: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
3830: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
3840: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
3850: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
3860: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3870: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
3880: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
3890: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
38a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
38b0: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
38c0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
38d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
38e0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
38f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
3900: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
3910: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
3920: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
3930: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3940: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3950: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3960: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
3970: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3980: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
3990: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
39a0: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
39b0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
39c0: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
39d0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
39e0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
39f0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
3a00: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
3a10: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
3a20: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
3a30: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3a40: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
3a50: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
3a60: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3a70: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3a80: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
3a90: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3aa0: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3ab0: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3ac0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3ad0: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
3ae0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3af0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3b00: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
3b10: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
3b20: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
3b30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3b40: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
3b50: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3b60: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
3b70: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
3b90: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3ba0: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3bb0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3bc0: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3bd0: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3be0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3bf0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3c00: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3c10: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3c20: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3c30: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3c40: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3c50: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3c60: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3c70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3c90: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3ca0: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3cb0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3cc0: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3cd0: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3ce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3cf0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3d00: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3d10: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3d20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3d30: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3d40: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3d50: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3d60: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3d70: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3d80: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3d90: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3da0: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3db0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3dc0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3dd0: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3de0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3df0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3e00: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3e10: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3e20: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3e30: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3e40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3e60: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3e70: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e80: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3e90: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3ea0: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3eb0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3ec0: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3ed0: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ee0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3ef0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3f00: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3f10: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3f20: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3f30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3f40: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3f50: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3f60: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3f70: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3f80: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3f90: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3fa0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3fb0: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3fc0: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3fd0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3fe0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3ff0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
4000: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
4010: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
4020: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
4030: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
4040: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
4050: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
4060: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
4070: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
4080: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
4090: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
40a0: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
40b0: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
40c0: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
40d0: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
40e0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
40f0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
4100: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
4110: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
4120: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
4130: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
4140: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4150: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
4160: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
4170: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
4180: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
4190: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
41a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
41b0: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
41c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
41d0: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
41e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
41f0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
4200: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
4210: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4220: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
4230: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4240: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4250: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4260: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4270: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
4280: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
4290: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
42a0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
42b0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
42c0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
42d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
42e0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
42f0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
4300: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4310: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4330: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4340: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4350: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4370: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4380: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4390: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
43a0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
43b0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
43c0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
43d0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
43e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4400: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4410: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4420: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4430: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4450: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4460: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4470: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4480: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4490: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
44a0: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
44b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
44c0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
44d0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
44e0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
44f0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
4500: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4510: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4520: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4530: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4540: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4550: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4560: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4570: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4580: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4590: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
45a0: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
45b0: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
45c0: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
45d0: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
45e0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
45f0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4610: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
4620: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72  /* Generic error
4630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4640: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4650: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4660: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4670: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4680: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4690: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
46a0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
46b0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
46c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
46d0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
46e0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
46f0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
4700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4710: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
4720: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4730: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4760: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4770: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4780: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4790: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
47a0: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
47b0: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
47c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
47d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
47e0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
47f0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
4800: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
4810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4820: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4830: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4840: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4850: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4870: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4880: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4890: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
48a0: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
48b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
48c0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
48d0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
48e0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
48f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4900: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
4910: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
4920: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4930: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4940: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4950: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4960: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4970: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4980: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4990: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
49a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
49b0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
49c0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
49d0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
49e0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
49f0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
4a00: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
4a10: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
4a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4a30: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4a40: 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20 6f  * Internal use o
4a50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
4a60: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4a70: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4a80: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4a90: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4aa0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4ab0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4ac0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
4ad0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
4ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4af0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4b00: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4b10: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4b20: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4b30: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4b40: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4b50: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4b60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b70: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4b80: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4b90: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bb0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4bc0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4bd0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4be0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4c00: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4c10: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4c20: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4c30: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4c40: 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 20      24   /* Not 
4c50: 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
4c60: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4c70: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4c80: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4c90: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4ca0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4cb0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4cc0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4cd0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
4ce0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
4cf0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
4d10: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4d20: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4d30: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4d50: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4d60: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4d70: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4d90: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4da0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4db0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4dc0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4dd0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4de0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4df0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4e00: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4e10: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4e20: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4e30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4e40: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4e50: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4e60: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4e70: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4e80: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4e90: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4ea0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4eb0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ec0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4ed0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4ee0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4ef0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4f00: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4f10: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4f20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f30: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4f40: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4f50: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4f60: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4f70: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4f80: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4f90: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4fa0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4fb0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4fc0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4fd0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4fe0: 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33  .3.8 [dateof:3.3
4ff0: 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72  .8].** and later
5000: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
5010: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
5020: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
5030: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
5040: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
5050: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
5060: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b   errors. These [
5070: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
5080: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c  codes] are enabl
5090: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
50a0: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
50b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
50c0: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
50d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
50e0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
50f0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68  ()] API.  Or, th
5100: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20  e extended code 
5110: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20  for.** the most 
5120: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e  recent error can
5130: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69   be obtained usi
5140: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
5150: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
5160: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
5170: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53 53  QLITE_ERROR_MISS
5180: 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28 53  ING_COLLSEQ   (S
5190: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 31  QLITE_ERROR | (1
51a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
51b0: 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52 59  LITE_ERROR_RETRY
51c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
51d0: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32 3c  LITE_ERROR | (2<
51e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
51f0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
5200: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5210: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5220: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5230: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
5240: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
5260: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5270: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5280: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
52a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52b0: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
52c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52d0: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
52e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52f0: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5300: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5310: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5330: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
5340: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5350: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5370: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5390: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
53a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53b0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
53c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53d0: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
53f0: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5400: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5410: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5470: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5490: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54b0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54d0: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54f0: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5510: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5530: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5540: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
5550: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
5560: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5570: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5580: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5590: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
55a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55b0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
55c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55d0: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
55e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55f0: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5600: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5610: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5620: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5630: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5640: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5650: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
5660: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5670: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5680: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5690: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
56a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56b0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
56c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56d0: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
56e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56f0: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5700: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5710: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5720: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5730: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5740: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5750: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5760: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5770: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5780: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5790: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
57a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57b0: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
57c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57d0: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
57e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57f0: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5800: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5810: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5820: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5830: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
5840: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5850: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
5860: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5870: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
5880: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5890: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
58a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58b0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
58c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58d0: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
58e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58f0: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20  _BEGIN_ATOMIC   
5900: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5910: 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66   | (29<<8)).#def
5920: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5930: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20  _COMMIT_ATOMIC  
5940: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5950: 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66   | (30<<8)).#def
5960: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5970: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
5980: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5990: 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66   | (31<<8)).#def
59a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
59b0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
59c0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
59d0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
59e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
59f0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5a00: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5a10: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5a30: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5a40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5a50: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5a60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5a70: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5a80: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5a90: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5aa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ab0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5ac0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5ad0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5ae0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5af0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5b00: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5b10: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5b20: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b30: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5b40: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5b50: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5b60: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5b70: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
5b80: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
5b90: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
5ba0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5bb0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 53  SQLITE_CORRUPT_S
5bc0: 45 51 55 45 4e 43 45 20 20 20 20 20 20 20 20 28  EQUENCE        (
5bd0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c  SQLITE_CORRUPT |
5be0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5bf0: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
5c00: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5c10: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
5c20: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5c30: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5c40: 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20  LY_CANTLOCK     
5c50: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5c60: 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  LY | (2<<8)).#de
5c70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5c80: 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  ONLY_ROLLBACK   
5c90: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5ca0: 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23  ONLY | (3<<8)).#
5cb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
5cc0: 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20  ADONLY_DBMOVED  
5cd0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
5ce0: 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29  ADONLY | (4<<8))
5cf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d00: 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49 4e 49  READONLY_CANTINI
5d10: 54 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  T       (SQLITE_
5d20: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c 3c 38  READONLY | (5<<8
5d30: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d40: 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52 45 43  E_READONLY_DIREC
5d50: 54 4f 52 59 20 20 20 20 20 20 28 53 51 4c 49 54  TORY      (SQLIT
5d60: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 36 3c  E_READONLY | (6<
5d70: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5d80: 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41  ITE_ABORT_ROLLBA
5d90: 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  CK          (SQL
5da0: 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c  ITE_ABORT | (2<<
5db0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5dc0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48  TE_CONSTRAINT_CH
5dd0: 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49  ECK        (SQLI
5de0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5df0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5e00: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5e10: 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28  T_COMMITHOOK   (
5e20: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5e30: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  T | (2<<8)).#def
5e40: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5e50: 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59  RAINT_FOREIGNKEY
5e60: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5e70: 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a  RAINT | (3<<8)).
5e80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5e90: 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49  ONSTRAINT_FUNCTI
5ea0: 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  ON     (SQLITE_C
5eb0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c  ONSTRAINT | (4<<
5ec0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5ed0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f  TE_CONSTRAINT_NO
5ee0: 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49  TNULL      (SQLI
5ef0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5f00: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
5f10: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5f20: 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28  T_PRIMARYKEY   (
5f30: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5f40: 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  T | (6<<8)).#def
5f50: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5f60: 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20  RAINT_TRIGGER   
5f70: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5f80: 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a  RAINT | (7<<8)).
5f90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5fa0: 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45  ONSTRAINT_UNIQUE
5fb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5fc0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c  ONSTRAINT | (8<<
5fd0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5fe0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54  TE_CONSTRAINT_VT
5ff0: 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  AB         (SQLI
6000: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
6010: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
6020: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
6030: 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 28  T_ROWID        (
6040: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
6050: 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66  T |(10<<8)).#def
6060: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
6070: 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20  E_RECOVER_WAL   
6080: 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43     (SQLITE_NOTIC
6090: 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  E | (1<<8)).#def
60a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
60b0: 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41  E_RECOVER_ROLLBA
60c0: 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43  CK (SQLITE_NOTIC
60d0: 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  E | (2<<8)).#def
60e0: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49  ine SQLITE_WARNI
60f0: 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20  NG_AUTOINDEX    
6100: 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49     (SQLITE_WARNI
6110: 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NG | (1<<8)).#de
6120: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
6130: 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20 20  _USER           
6140: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48      (SQLITE_AUTH
6150: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
6160: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41  ne SQLITE_OK_LOA
6170: 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20  D_PERMANENTLY   
6180: 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28    (SQLITE_OK | (
6190: 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  1<<8))../*.** CA
61a0: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f  PI3REF: Flags Fo
61b0: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72  r File Open Oper
61c0: 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ations.**.** The
61d0: 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72  se bit values ar
61e0: 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
61f0: 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64  se in the.** 3rd
6200: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
6210: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
6220: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
6230: 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74  and.** in the 4t
6240: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
6250: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
6260: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a  xOpen] method..*
6270: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6280: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20  _OPEN_READONLY  
6290: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
62a0: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  1  /* Ok for sql
62b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
62c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
62d0: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
62e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
62f0: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  2  /* Ok for sql
6300: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6310: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6320: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20  _OPEN_CREATE    
6330: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6340: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  4  /* Ok for sql
6350: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6360: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6370: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
6380: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30  OSE    0x0000000
6390: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  8  /* VFS only *
63a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
63b0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
63c0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
63d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
63e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
63f0: 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20  _OPEN_AUTOPROXY 
6400: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
6410: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6420: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6430: 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20  _OPEN_URI       
6440: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
6450: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6460: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6470: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6480: 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20  _OPEN_MEMORY    
6490: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
64a0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
64b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
64c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
64d0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20  _OPEN_MAIN_DB   
64e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
64f0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6500: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6510: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20  _OPEN_TEMP_DB   
6520: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6530: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6540: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6550: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
6560: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30  DB     0x0000040
6570: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6580: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6590: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
65a0: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30  AL     0x0000080
65b0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
65c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
65d0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
65e0: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30  AL     0x0000100
65f0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6600: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6610: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
6620: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
6630: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6640: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6650: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
6660: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30  RNAL   0x0000400
6670: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6680: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6690: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20  _OPEN_NOMUTEX   
66a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30         0x0000800
66b0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
66c0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
66d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
66e0: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20  _OPEN_FULLMUTEX 
66f0: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30         0x0001000
6700: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6710: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6720: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6730: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
6740: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30  E      0x0002000
6750: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6760: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6770: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6780: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
6790: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30  HE     0x0004000
67a0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
67b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
67c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
67d0: 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20  _OPEN_WAL       
67e0: 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30         0x0008000
67f0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6800: 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20  /../* Reserved: 
6810: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6820: 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30          0x00F000
6830: 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00 */../*.** CAP
6840: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
6850: 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a  aracteristics.**
6860: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43  .** The xDeviceC
6870: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
6880: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71  ethod of the [sq
6890: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
68a0: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75  ].** object retu
68b0: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77  rns an integer w
68c0: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72  hich is a vector
68d0: 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74   of these.** bit
68e0: 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69   values expressi
68f0: 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72  ng I/O character
6900: 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61  istics of the ma
6910: 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65  ss storage.** de
6920: 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20  vice that holds 
6930: 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68  the file that th
6940: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6950: 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73  thods].** refers
6960: 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53   to..**.** The S
6970: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6980: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
6990: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
69a0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
69b0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
69c0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
69d0: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
69e0: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
69f0: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
6a00: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
6a10: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
6a20: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
6a30: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
6a40: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
6a50: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
6a60: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6a70: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6a80: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
6a90: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
6aa0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
6ab0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
6ac0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
6ad0: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
6ae0: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
6af0: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
6b00: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
6b10: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
6b20: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
6b30: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6b40: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6b50: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
6b60: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
6b70: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
6b80: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
6b90: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
6ba0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6bb0: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
6bc0: 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79  ERWRITE property
6bd0: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61   means that.** a
6be0: 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c  fter reboot foll
6bf0: 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72  owing a crash or
6c00: 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65   power loss, the
6c10: 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61   only bytes in a
6c20: 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65  .** file that we
6c30: 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68  re written at th
6c40: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65  e application le
6c50: 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63  vel might have c
6c60: 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68  hanged.** and th
6c70: 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65  at adjacent byte
6c80: 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69  s, even bytes wi
6c90: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65  thin the same se
6ca0: 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72  ctor are.** guar
6cb0: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63  anteed to be unc
6cc0: 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c  hanged.  The SQL
6cd0: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
6ce0: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a  TABLE_WHEN_OPEN.
6cf0: 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65  ** flag indicate
6d00: 73 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61  s that a file ca
6d10: 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20  nnot be deleted 
6d20: 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a  when open.  The.
6d30: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ** SQLITE_IOCAP_
6d40: 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69  IMMUTABLE flag i
6d50: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
6d60: 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20  e file is on.** 
6d70: 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20  read-only media 
6d80: 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  and cannot be ch
6d90: 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72  anged even by pr
6da0: 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20  ocesses with.** 
6db0: 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65  elevated privile
6dc0: 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  ges..**.** The S
6dd0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43  QLITE_IOCAP_BATC
6de0: 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  H_ATOMIC propert
6df0: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  y means that the
6e00: 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 66   underlying.** f
6e10: 69 6c 65 73 79 73 74 65 6d 20 73 75 70 70 6f 72  ilesystem suppor
6e20: 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69 70 6c  ts doing multipl
6e30: 65 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f  e write operatio
6e40: 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20 77 68  ns atomically wh
6e50: 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72 69 74  en those.** writ
6e60: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  e operations are
6e70: 20 62 72 61 63 6b 65 74 65 64 20 62 79 20 5b 53   bracketed by [S
6e80: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
6e90: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  N_ATOMIC_WRITE] 
6ea0: 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  and.** [SQLITE_F
6eb0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d  CNTL_COMMIT_ATOM
6ec0: 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a 23 64  IC_WRITE]..*/.#d
6ed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6ee0: 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20  AP_ATOMIC       
6ef0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6f00: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
6f10: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6f20: 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20  512             
6f30: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
6f40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6f50: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20  _ATOMIC1K       
6f60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6f70: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
6f80: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
6f90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6fa0: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e  x00000008.#defin
6fb0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6fc0: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20  TOMIC4K         
6fd0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
6fe0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6ff0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20  IOCAP_ATOMIC8K  
7000: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
7010: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20  0000020.#define 
7020: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7030: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20  MIC16K          
7040: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23      0x00000040.#
7050: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7060: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20  CAP_ATOMIC32K   
7070: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
7080: 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51  00080.#define SQ
7090: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
70a0: 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  C64K            
70b0: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
70c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
70d0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20  P_SAFE_APPEND   
70e0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
70f0: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
7100: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
7110: 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  IAL             
7120: 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69  0x00000400.#defi
7130: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
7140: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
7150: 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30  _OPEN  0x0000080
7160: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
7170: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
7180: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78  _OVERWRITE    0x
7190: 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65  00001000.#define
71a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d   SQLITE_IOCAP_IM
71b0: 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  MUTABLE         
71c0: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a       0x00002000.
71d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
71e0: 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d 49  OCAP_BATCH_ATOMI
71f0: 43 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  C           0x00
7200: 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  004000../*.** CA
7210: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
7220: 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a  king Levels.**.*
7230: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
7240: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
7250: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
7260: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
7270: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
7280: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
7290: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
72a0: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
72b0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
72c0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
72d0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
72e0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
72f0: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
7300: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7310: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
7320: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
7330: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
7340: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
7350: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
7360: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
7370: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
7380: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
7390: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
73a0: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
73b0: 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  ags.**.** When S
73c0: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
73d0: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
73e0: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
73f0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
7400: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
7410: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
7420: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
7430: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
7440: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
7450: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
7460: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
7470: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
7480: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
7490: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
74a0: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
74b0: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
74c0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
74d0: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
74e0: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
74f0: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65   flushed. If the
7500: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
7510: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20   of the flag.** 
7520: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
7530: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d  C_NORMAL, that m
7540: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d  eans to use norm
7550: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
7560: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  tics..** If the 
7570: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
7580: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
7590: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61  C_FULL, that mea
75a0: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  ns.** to use Mac
75b0: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
75c0: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
75d0: 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44  fsync()..**.** D
75e0: 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68  o not confuse th
75f0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
7600: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
7610: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a  SYNC_FULL flags.
7620: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41  ** with the [PRA
7630: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
7640: 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41  =NORMAL and [PRA
7650: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
7660: 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67  =FULL.** setting
7670: 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f  s.  The [synchro
7680: 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74  nous pragma] det
7690: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c  ermines when cal
76a0: 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79  ls to the.** xSy
76b0: 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63  nc VFS method oc
76c0: 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20  cur and applies 
76d0: 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73  uniformly across
76e0: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a   all platforms..
76f0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  ** The SQLITE_SY
7700: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
7710: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
7720: 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68  lags determine h
7730: 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20  ow.** energetic 
7740: 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66  or rigorous or f
7750: 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63  orceful the sync
7760: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
7770: 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65  and.** only make
7780: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e   a difference on
7790: 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65   Mac OSX for the
77a0: 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20   default SQLite 
77b0: 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d  code..** (Third-
77c0: 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d  party VFS implem
77d0: 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  entations might 
77e0: 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69  also make the di
77f0: 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
7800: 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43  ween SQLITE_SYNC
7810: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
7820: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75  TE_SYNC_FULL, bu
7830: 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f  t among the.** o
7840: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73  perating systems
7850: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72   natively suppor
7860: 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f  ted by SQLite, o
7870: 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63  nly Mac OSX.** c
7880: 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64  ares about the d
7890: 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23  ifference.).*/.#
78a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
78b0: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
78c0: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
78d0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
78e0: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
78f0: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
7900: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
7910: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
7920: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
7930: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
7940: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  File Handle.**.*
7950: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
7960: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
7970: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
7980: 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73  le in the .** [s
7990: 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20  qlite3_vfs | OS 
79a0: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d  interface layer]
79b0: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
79c0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d   interface.** im
79d0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
79e0: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75  ll.** want to su
79f0: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65  bclass this obje
7a00: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20  ct by appending 
7a10: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
7a20: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f  s.** for their o
7a30: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65  wn use.  The pMe
7a40: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61  thods entry is a
7a50: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
7a60: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
7a70: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68  thods] object th
7a80: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f  at defines metho
7a90: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e  ds for performin
7aa0: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69  g.** I/O operati
7ab0: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20  ons on the open 
7ac0: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  file..*/.typedef
7ad0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7ae0: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c  file sqlite3_fil
7af0: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  e;.struct sqlite
7b00: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74  3_file {.  const
7b10: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7b20: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74  io_methods *pMet
7b30: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64  hods;  /* Method
7b40: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69  s for an open fi
7b50: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  le */.};../*.** 
7b60: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
7b70: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74  erface File Virt
7b80: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  ual Methods Obje
7b90: 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  ct.**.** Every f
7ba0: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
7bb0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7bc0: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70  Open] method pop
7bd0: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
7be0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7bf0: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
7c00: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
7c10: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
7c20: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7c30: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
7c40: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
7c50: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
7c60: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
7c70: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
7c80: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
7c90: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
7ca0: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
7cb0: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
7cc0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
7cd0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
7ce0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7cf0: 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  If the [sqlite3_
7d00: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
7d10: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
7d20: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7d30: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
7d40: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
7d50: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
7d60: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
7d70: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
7d80: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
7d90: 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c  even if the [sql
7da0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7db0: 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74  reported that it
7dc0: 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a   failed.  The.**
7dd0: 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65   only way to pre
7de0: 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78  vent a call to x
7df0: 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  Close following 
7e00: 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65  a failed [sqlite
7e10: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20  3_vfs.xOpen].** 
7e20: 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  is for the [sqli
7e30: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74  te3_vfs.xOpen] t
7e40: 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  o set the sqlite
7e50: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
7e60: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55  element.** to NU
7e70: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
7e80: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
7e90: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
7ea0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
7eb0: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
7ec0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7ed0: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
7ee0: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
7ef0: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
7f00: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
7f10: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
7f20: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
7f30: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
7f40: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
7f50: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
7f60: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
7f70: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
7f80: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
7f90: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
7fa0: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
7fb0: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
7fc0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
7fd0: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
7fe0: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
7ff0: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
8000: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
8010: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
8020: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
8030: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
8040: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
8050: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
8060: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
8070: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
8080: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
8090: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
80a0: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
80b0: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
80c0: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
80d0: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
80e0: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
80f0: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
8100: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
8110: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
8120: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
8130: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
8140: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
8150: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
8160: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
8170: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
8180: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
8190: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
81a0: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
81b0: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
81c0: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
81d0: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
81e0: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
81f0: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
8200: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
8210: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
8220: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
8230: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
8240: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
8250: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
8260: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
8270: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
8280: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
8290: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
82a0: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
82b0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
82c0: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
82d0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
82e0: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
82f0: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
8300: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
8310: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
8320: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
8330: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
8340: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
8350: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
8360: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
8370: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
8380: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
8390: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
83a0: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
83b0: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
83c0: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
83d0: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
83e0: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
83f0: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
8400: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
8410: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
8420: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
8430: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
8440: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
8450: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
8460: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
8470: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
8480: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
8490: 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   [file control o
84a0: 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66  pcodes | list of
84b0: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
84c0: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
84d0: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
84e0: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
84f0: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
8500: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
8510: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
8520: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61  s.** greater tha
8530: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63  n 100 to avoid c
8540: 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69  onflicts.  VFS i
8550: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
8560: 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
8570: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
8580: 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72  ] for file contr
8590: 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20  ol opcodes that 
85a0: 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72  they do not.** r
85b0: 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20  ecognize..**.** 
85c0: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
85d0: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
85e0: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
85f0: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
8600: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
8610: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
8620: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
8630: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
8640: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
8650: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
8660: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
8670: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
8680: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
8690: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
86a0: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
86b0: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
86c0: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
86d0: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
86e0: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
86f0: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
8700: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
8710: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d  TE_IOCAP_ATOMIC]
8720: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8730: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
8740: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8750: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
8760: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8770: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
8780: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8790: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
87a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
87b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
87c0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
87d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
87e0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
87f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
8800: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
8810: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8820: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  64K].** <li> [SQ
8830: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
8840: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20  APPEND].** <li> 
8850: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45  [SQLITE_IOCAP_SE
8860: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69  QUENTIAL].** <li
8870: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8880: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
8890: 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  _OPEN].** <li> [
88a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
88b0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
88c0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
88d0: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
88e0: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
88f0: 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41  TE_IOCAP_BATCH_A
8900: 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  TOMIC].** </ul>.
8910: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
8920: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
8930: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
8940: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
8950: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
8960: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
8970: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8980: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
8990: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
89a0: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
89b0: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
89c0: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
89d0: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
89e0: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
89f0: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
8a00: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
8a10: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
8a20: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
8a30: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
8a40: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
8a50: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
8a60: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
8a70: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
8a80: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
8a90: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
8aa0: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
8ab0: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
8ac0: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
8ad0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8ae0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
8af0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
8b00: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
8b10: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
8b20: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
8b30: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
8b40: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a  to xWrite()..**.
8b50: 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65  ** If xRead() re
8b60: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45  turns SQLITE_IOE
8b70: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74  RR_SHORT_READ it
8b80: 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a   must also fill.
8b90: 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64  ** in the unread
8ba0: 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65   portions of the
8bb0: 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72   buffer with zer
8bc0: 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a  os.  A VFS that.
8bd0: 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f  ** fails to zero
8be0: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
8bf0: 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20  s might seem to 
8c00: 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a  work.  However,.
8c10: 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65  ** failure to ze
8c20: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
8c30: 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61  ads will eventua
8c40: 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64  lly lead to.** d
8c50: 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
8c60: 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
8c70: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
8c80: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
8c90: 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  _io_methods;.str
8ca0: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
8cb0: 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69  ethods {.  int i
8cc0: 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
8cd0: 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
8ce0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8cf0: 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f  *xRead)(sqlite3_
8d00: 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e  file*, void*, in
8d10: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
8d20: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
8d30: 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71  int (*xWrite)(sq
8d40: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e  lite3_file*, con
8d50: 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  st void*, int iA
8d60: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
8d70: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
8d80: 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c  (*xTruncate)(sql
8d90: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8da0: 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b  te3_int64 size);
8db0: 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28  .  int (*xSync)(
8dc0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8dd0: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74  nt flags);.  int
8de0: 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71   (*xFileSize)(sq
8df0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
8e00: 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a  ite3_int64 *pSiz
8e10: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63  e);.  int (*xLoc
8e20: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8e30: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
8e40: 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33  xUnlock)(sqlite3
8e50: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
8e60: 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65  int (*xCheckRese
8e70: 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65  rvedLock)(sqlite
8e80: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52  3_file*, int *pR
8e90: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
8ea0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71  xFileControl)(sq
8eb0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8ec0: 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29   op, void *pArg)
8ed0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f  ;.  int (*xSecto
8ee0: 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  rSize)(sqlite3_f
8ef0: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
8f00: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
8f10: 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66  stics)(sqlite3_f
8f20: 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  ile*);.  /* Meth
8f30: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
8f40: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
8f50: 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68  1 */.  int (*xSh
8f60: 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  mMap)(sqlite3_fi
8f70: 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e  le*, int iPg, in
8f80: 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69  t pgsz, int, voi
8f90: 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20  d volatile**);. 
8fa0: 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29   int (*xShmLock)
8fb0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8fc0: 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20  int offset, int 
8fd0: 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  n, int flags);. 
8fe0: 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72   void (*xShmBarr
8ff0: 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ier)(sqlite3_fil
9000: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  e*);.  int (*xSh
9010: 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f  mUnmap)(sqlite3_
9020: 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74  file*, int delet
9030: 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74  eFlag);.  /* Met
9040: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
9050: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
9060: 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46   2 */.  int (*xF
9070: 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69  etch)(sqlite3_fi
9080: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
9090: 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41  64 iOfst, int iA
90a0: 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a  mt, void **pp);.
90b0: 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68    int (*xUnfetch
90c0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
90d0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
90e0: 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a  Ofst, void *p);.
90f0: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
9100: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
9110: 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20   version 3 */.  
9120: 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65  /* Additional me
9130: 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64  thods may be add
9140: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
9150: 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  eases */.};../*.
9160: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61  ** CAPI3REF: Sta
9170: 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72  ndard File Contr
9180: 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45  ol Opcodes.** KE
9190: 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f  YWORDS: {file co
91a0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b  ntrol opcodes} {
91b0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
91c0: 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ode}.**.** These
91d0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
91e0: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
91f0: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
9200: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
9210: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
9220: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
9230: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71   and for the [sq
9240: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9250: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ol()].** interfa
9260: 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ce..**.** <ul>.*
9270: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9280: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d  CNTL_LOCKSTATE]]
9290: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
92a0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
92b0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
92c0: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
92d0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
92e0: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
92f0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
9300: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
9310: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
9320: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
9330: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
9340: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
9350: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
9360: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
9370: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
9380: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
9390: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
93a0: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
93b0: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
93c0: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
93d0: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69  t points to. Thi
93e0: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
93f0: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
9400: 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e  esting and is on
9410: 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65  ly available whe
9420: 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53  n the SQLITE_TES
9430: 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  T.** compile-tim
9440: 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  e option is used
9450: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9460: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
9470: 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  HINT]].** The [S
9480: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
9490: 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73  _HINT] opcode is
94a0: 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20   used by SQLite 
94b0: 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a  to give the VFS.
94c0: 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20  ** layer a hint 
94d0: 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65  of how large the
94e0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
94f0: 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64  ill grow to be d
9500: 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72  uring the.** cur
9510: 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  rent transaction
9520: 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
9530: 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74  not guaranteed t
9540: 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75  o be accurate bu
9550: 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e  t it.** is often
9560: 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64   close.  The und
9570: 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68  erlying VFS migh
9580: 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61  t choose to prea
9590: 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65  llocate database
95a0: 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62  .** file space b
95b0: 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e  ased on this hin
95c0: 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65  t in order to he
95d0: 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65  lp writes to the
95e0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
95f0: 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a  e run faster..**
9600: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9610: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
9620: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
9630: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
9640: 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  IZE] opcode is u
9650: 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74  sed to request t
9660: 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65  hat the VFS.** e
9670: 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63  xtends and trunc
9680: 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ates the databas
9690: 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73  e file in chunks
96a0: 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69   of a size speci
96b0: 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75  fied.** by the u
96c0: 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ser. The fourth 
96d0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
96e0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
96f0: 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20  l()] should .** 
9700: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65  point to an inte
9710: 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63  ger (type int) c
9720: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65  ontaining the ne
9730: 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20  w chunk-size to 
9740: 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e  use.** for the n
9750: 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73  ominated databas
9760: 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61  e. Allocating da
9770: 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63  tabase file spac
9780: 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68  e in large.** ch
9790: 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74  unks (say 1MB at
97a0: 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65   a time), may re
97b0: 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d  duce file-system
97c0: 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61   fragmentation a
97d0: 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65  nd.** improve pe
97e0: 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d  rformance on som
97f0: 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a  e systems..**.**
9800: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9810: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
9820: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9830: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
9840: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
9850: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
9860: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
9870: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
9880: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
9890: 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69  ted with a parti
98a0: 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a  cular database.*
98b0: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53  * connection.  S
98c0: 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f  ee also [SQLITE_
98d0: 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f  FCNTL_JOURNAL_PO
98e0: 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  INTER]..**.** <l
98f0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9900: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
9910: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9920: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
9930: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
9940: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
9950: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
9960: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
9970: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
9980: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
9990: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 69  journal file (ei
99a0: 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c  ther.** the [rol
99b0: 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f  lback journal] o
99c0: 72 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68 65  r the [write-ahe
99d0: 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70  ad log]) for a p
99e0: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
99f0: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
9a00: 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c  .  See also [SQL
9a10: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
9a20: 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  OINTER]..**.** <
9a30: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9a40: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d  L_SYNC_OMITTED]]
9a50: 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e  .** No longer in
9a60: 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e   use..**.** <li>
9a70: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
9a80: 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  YNC]].** The [SQ
9a90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d  LITE_FCNTL_SYNC]
9aa0: 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72   opcode is gener
9ab0: 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ated internally 
9ac0: 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a  by SQLite and.**
9ad0: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53   sent to the VFS
9ae0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66   immediately bef
9af0: 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65  ore the xSync me
9b00: 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
9b10: 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65  on a.** database
9b20: 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72   file descriptor
9b30: 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79  . Or, if the xSy
9b40: 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74  nc method is not
9b50: 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63   invoked .** bec
9b60: 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61  ause the user ha
9b70: 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c  s configured SQL
9b80: 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52  ite with .** [PR
9b90: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
9ba0: 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72   | PRAGMA synchr
9bb0: 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73  onous=OFF] it is
9bc0: 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63   invoked in plac
9bd0: 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79  e .** of the xSy
9be0: 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f  nc method. In mo
9bf0: 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f  st cases, the po
9c00: 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70  inter argument p
9c10: 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  assed with.** th
9c20: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  is file-control 
9c30: 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72  is NULL. However
9c40: 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73  , if the databas
9c50: 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20  e file is being 
9c60: 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72  synced.** as par
9c70: 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74  t of a multi-dat
9c80: 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68  abase commit, th
9c90: 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  e argument point
9ca0: 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69  s to a nul-termi
9cb0: 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
9cc0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74  containing the t
9cd0: 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74  ransactions mast
9ce0: 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20  er-journal file 
9cf0: 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74  name. VFSes that
9d00: 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64   .** do not need
9d10: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f   this signal sho
9d20: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
9d30: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
9d40: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a   Applications .*
9d50: 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  * should not cal
9d60: 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  l [sqlite3_file_
9d70: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
9d80: 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64  this opcode as d
9d90: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20  oing so may .** 
9da0: 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72  disrupt the oper
9db0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
9dc0: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74  cialized VFSes t
9dd0: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
9de0: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
9df0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
9e00: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a  MMIT_PHASETWO]].
9e10: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9e20: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
9e30: 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20  ETWO] opcode is 
9e40: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e  generated intern
9e50: 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a  ally by SQLite.*
9e60: 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68  * and sent to th
9e70: 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72  e VFS after a tr
9e80: 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65  ansaction has be
9e90: 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d  en committed imm
9ea0: 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20  ediately.** but 
9eb0: 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62  before the datab
9ec0: 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e  ase is unlocked.
9ed0: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e   VFSes that do n
9ee0: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  ot need this sig
9ef0: 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69  nal.** should si
9f00: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
9f10: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69  is opcode. Appli
9f20: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e  cations should n
9f30: 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  ot call.** [sqli
9f40: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9f50: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70  ()] with this op
9f60: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
9f70: 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65   may disrupt the
9f80: 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f   .** operation o
9f90: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
9fa0: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  d VFSes that do 
9fb0: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
9fc0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9fd0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
9fe0: 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20  RETRY]].** ^The 
9ff0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
a000: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70  N32_AV_RETRY] op
a010: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
a020: 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61  configure automa
a030: 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75  tic.** retry cou
a040: 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c  nts and interval
a050: 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69  s for certain di
a060: 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  sk I/O operation
a070: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e  s for the.** win
a080: 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72  dows [VFS] in or
a090: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72  der to provide r
a0a0: 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65  obustness in the
a0b0: 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20   presence of.** 
a0c0: 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72  anti-virus progr
a0d0: 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ams.  By default
a0e0: 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46  , the windows VF
a0f0: 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c  S will retry fil
a100: 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20  e read,.** file 
a110: 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20  write, and file 
a120: 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e  delete operation
a130: 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73  s up to 10 times
a140: 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a  , with a delay.*
a150: 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63  * of 25 millisec
a160: 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20  onds before the 
a170: 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20  first retry and 
a180: 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69  with the delay i
a190: 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20  ncreasing.** by 
a1a0: 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35  an additional 25
a1b0: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69   milliseconds wi
a1c0: 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65  th each subseque
a1d0: 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a  nt retry.  This.
a1e0: 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73  ** opcode allows
a1f0: 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65   these two value
a200: 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e  s (10 retries an
a210: 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  d 25 millisecond
a220: 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74  s of delay).** t
a230: 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20  o be adjusted.  
a240: 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63  The values are c
a250: 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64  hanged for all d
a260: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
a270: 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68  ons.** within th
a280: 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20  e same process. 
a290: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
a2a0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
a2b0: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a   array of two.**
a2c0: 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20   integers where 
a2d0: 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65  the first intege
a2e0: 72 20 69 73 20 74 68 65 20 6e 65 77 20 72 65 74  r is the new ret
a2f0: 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65  ry count and the
a300: 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67   second.** integ
a310: 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e  er is the delay.
a320: 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65    If either inte
a330: 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ger is negative,
a340: 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e   then the settin
a350: 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  g.** is not chan
a360: 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20  ged but instead 
a370: 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
a380: 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20  of that setting 
a390: 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e  is written.** in
a3a0: 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74  to the array ent
a3b0: 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65  ry, allowing the
a3c0: 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73   current retry s
a3d0: 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a  ettings to be.**
a3e0: 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20   interrogated.  
a3f0: 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61  The zDbName para
a400: 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64  meter is ignored
a410: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a420: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
a430: 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65  ST_WAL]].** ^The
a440: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a450: 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f  ERSIST_WAL] opco
a460: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
a470: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
a480: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41  * persistent [WA
a490: 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20  L | Write Ahead 
a4a0: 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42  Log] setting.  B
a4b0: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61  y default, the a
a4c0: 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74  uxiliary.** writ
a4d0: 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20  e ahead log and 
a4e0: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
a4f0: 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61  les used for tra
a500: 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
a510: 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69  .** are automati
a520: 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68  cally deleted wh
a530: 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f  en the latest co
a540: 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20  nnection to the 
a550: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73  database.** clos
a560: 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72  es.  Setting per
a570: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
a580: 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69   causes those fi
a590: 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61  les to persist a
a5a0: 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20  fter.** close.  
a5b0: 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66  Persisting the f
a5c0: 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77  iles is useful w
a5d0: 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73  hen other proces
a5e0: 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a  ses that do not.
a5f0: 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65  ** have write pe
a600: 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20  rmission on the 
a610: 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69  directory contai
a620: 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
a630: 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74  e file want.** t
a640: 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62  o read the datab
a650: 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65  ase file, as the
a660: 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20   WAL and shared 
a670: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73  memory files mus
a680: 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72  t exist.** in or
a690: 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61  der for the data
a6a0: 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61  base to be reada
a6b0: 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68  ble.  The fourth
a6c0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
a6d0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
a6e0: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
a6f0: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
a700: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
a710: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
a720: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
a730: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72  0 to disable per
a740: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
a750: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a760: 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41  persistent.** WA
a770: 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  L mode.  If the 
a780: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
a790: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
a7a0: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
a7b0: 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65  urrent.** WAL pe
a7c0: 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e  rsistence settin
a7d0: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
a7e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
a7f0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
a800: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a810: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
a820: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63  E_OVERWRITE] opc
a830: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
a840: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
a850: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70  ** persistent "p
a860: 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69  owersafe-overwri
a870: 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65  te" or "PSOW" se
a880: 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57  tting.  The PSOW
a890: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65   setting.** dete
a8a0: 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49  rmines the [SQLI
a8b0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
a8c0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69  FE_OVERWRITE] bi
a8d0: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76  t of the.** xDev
a8e0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
a8f0: 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20  cs methods. The 
a900: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
a910: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
a920: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
a930: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
a940: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
a950: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
a960: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
a970: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
a980: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  le zero-damage m
a990: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62  ode or 1 to enab
a9a0: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a  le zero-damage.*
a9b0: 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  * mode.  If the 
a9c0: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
a9d0: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
a9e0: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
a9f0: 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64  urrent.** zero-d
aa00: 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69  amage mode setti
aa10: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
aa20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
aa30: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
aa40: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f   [SQLITE_FCNTL_O
aa50: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
aa60: 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53   is invoked by S
aa70: 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e  QLite after open
aa80: 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74  ing.** a write t
aa90: 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e  ransaction to in
aaa0: 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c  dicate that, unl
aab0: 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64  ess it is rolled
aac0: 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a   back for some.*
aad0: 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e  * reason, the en
aae0: 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69  tire database fi
aaf0: 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77  le will be overw
ab00: 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75  ritten by the cu
ab10: 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61  rrent .** transa
ab20: 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75  ction. This is u
ab30: 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70  sed by VACUUM op
ab40: 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
ab50: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
ab60: 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20  TL_VFSNAME]].** 
ab70: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
ab80: 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f  TL_VFSNAME] opco
ab90: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  de can be used t
aba0: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d  o obtain the nam
abb0: 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46  es of.** all [VF
abc0: 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20  Ses] in the VFS 
abd0: 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65  stack.  The name
abe0: 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53  s are of all VFS
abf0: 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a   shims and the.*
ac00: 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c  * final bottom-l
ac10: 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69  evel VFS are wri
ac20: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
ac30: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a   obtained from .
ac40: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
ac50: 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65  oc()] and the re
ac60: 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69  sult is stored i
ac70: 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69  n the char* vari
ac80: 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65  able.** that the
ac90: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
aca0: 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69  r of [sqlite3_fi
acb0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f  le_control()] po
acc0: 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20  ints to..** The 
acd0: 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e  caller is respon
ace0: 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e  sible for freein
acf0: 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65  g the memory whe
ad00: 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68  n done.  As with
ad10: 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e  .** all file-con
ad20: 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68  trol actions, th
ad30: 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e  ere is no guaran
ad40: 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69  tee that this wi
ad50: 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64  ll actually.** d
ad60: 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c  o anything.  Cal
ad70: 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74  lers should init
ad80: 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a  ialize the char*
ad90: 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e   variable to a N
ada0: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ULL.** pointer i
adb0: 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65  n case this file
adc0: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20  -control is not 
add0: 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68  implemented.  Th
ade0: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a  is file-control.
adf0: 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66  ** is intended f
ae00: 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73  or diagnostic us
ae10: 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  e only..**.** <l
ae20: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ae30: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a  _VFS_POINTER]].*
ae40: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
ae50: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
ae60: 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 61  ] opcode finds a
ae70: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
ae80: 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46  top-level.** [VF
ae90: 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 69  Ses] currently i
aea0: 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61 72  n use.  ^(The ar
aeb0: 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73  gument X in.** s
aec0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
aed0: 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 43  rol(db,SQLITE_FC
aee0: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c  NTL_VFS_POINTER,
aef0: 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66  X) must be.** of
af00: 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33 5f   type "[sqlite3_
af10: 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20  vfs] **".  This 
af20: 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 74  opcodes will set
af30: 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e   *X.** to a poin
af40: 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c  ter to the top-l
af50: 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e  evel VFS.)^.** ^
af60: 57 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6d  When there are m
af70: 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69 6d  ultiple VFS shim
af80: 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c 20  s in the stack, 
af90: 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e 64  this opcode find
afa0: 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d  s the.** upper-m
afb0: 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a  ost shim only..*
afc0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
afd0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d  E_FCNTL_PRAGMA]]
afe0: 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20  .** ^Whenever a 
aff0: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
b000: 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e  nt is parsed, an
b010: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
b020: 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20  RAGMA] .** file 
b030: 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20  control is sent 
b040: 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c  to the open [sql
b050: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
b060: 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  t corresponding.
b070: 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ** to the databa
b080: 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68  se file to which
b090: 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74   the pragma stat
b0a0: 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54  ement refers. ^T
b0b0: 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  he argument.** t
b0c0: 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  o the [SQLITE_FC
b0d0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
b0e0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61   control is an a
b0f0: 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74  rray of.** point
b100: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28  ers to strings (
b110: 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68  char**) in which
b120: 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d   the second elem
b130: 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79  ent of the array
b140: 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
b150: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e  of the pragma an
b160: 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d  d the third elem
b170: 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ent is the argum
b180: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72  ent to the.** pr
b190: 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20  agma or NULL if 
b1a0: 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e  the pragma has n
b1b0: 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68  o argument.  ^Th
b1c0: 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e  e handler for an
b1d0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
b1e0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
b1f0: 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f  ontrol can optio
b200: 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66  nally make the f
b210: 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  irst element.** 
b220: 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72  of the char** ar
b230: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20  gument point to 
b240: 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  a string obtaine
b250: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
b260: 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72  mprintf()].** or
b270: 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20   the equivalent 
b280: 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20  and that string 
b290: 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20  will become the 
b2a0: 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72  result of the pr
b2b0: 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65  agma or.** the e
b2c0: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20  rror message if 
b2d0: 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73  the pragma fails
b2e0: 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51  . ^If the.** [SQ
b2f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
b300: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
b310: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
b320: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20  NOTFOUND], then 
b330: 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47  normal .** [PRAG
b340: 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63  MA] processing c
b350: 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74  ontinues.  ^If t
b360: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b370: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
b380: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
b390: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
b3a0: 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73  en the parser as
b3b0: 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
b3c0: 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65  * VFS has handle
b3d0: 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73  d the PRAGMA its
b3e0: 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73  elf and the pars
b3f0: 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e  er generates a n
b400: 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64  o-op.** prepared
b410: 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65   statement if re
b420: 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e  sult string is N
b430: 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74  ULL, or that ret
b440: 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  urns a copy.** o
b450: 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 74 72  f the result str
b460: 69 6e 67 20 69 66 20 74 68 65 20 73 74 72 69 6e  ing if the strin
b470: 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a  g is non-NULL..*
b480: 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
b490: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
b4a0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
b4b0: 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75  urns.** any resu
b4c0: 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68  lt code other th
b4d0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  an [SQLITE_OK] o
b4e0: 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  r [SQLITE_NOTFOU
b4f0: 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ND], that means.
b500: 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20  ** that the VFS 
b510: 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65  encountered an e
b520: 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c  rror while handl
b530: 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d  ing the [PRAGMA]
b540: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70   and the.** comp
b550: 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50  ilation of the P
b560: 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68  RAGMA fails with
b570: 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65   an error.  ^The
b580: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
b590: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
b5a0: 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74  ontrol occurs at
b5b0: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
b5c0: 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  f pragma stateme
b5d0: 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20  nt analysis and 
b5e0: 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65  so.** it is able
b5f0: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69   to override bui
b600: 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73  lt-in [PRAGMA] s
b610: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
b620: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b630: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
b640: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
b650: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
b660: 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  LER].** file-con
b670: 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f  trol may be invo
b680: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e  ked by SQLite on
b690: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
b6a0: 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f  le handle.** sho
b6b0: 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73  rtly after it is
b6c0: 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72   opened in order
b6d0: 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75   to provide a cu
b6e0: 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63  stom VFS with ac
b6f0: 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  cess.** to the c
b700: 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d  onnections busy-
b710: 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
b720: 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  . The argument i
b730: 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20  s of type (void 
b740: 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61  **).** - an arra
b750: 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a  y of two (void *
b760: 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69  ) values. The fi
b770: 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74  rst (void *) act
b780: 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20  ually points.** 
b790: 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
b7a0: 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76   type (int (*)(v
b7b0: 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65  oid *)). In orde
b7c0: 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20  r to invoke the 
b7d0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62  connections.** b
b7e0: 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69  usy-handler, thi
b7f0: 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  s function shoul
b800: 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  d be invoked wit
b810: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f  h the second (vo
b820: 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20  id *) in.** the 
b830: 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c  array as the onl
b840: 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69  y argument. If i
b850: 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  t returns non-ze
b860: 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65  ro, then the ope
b870: 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  ration.** should
b880: 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20   be retried. If 
b890: 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  it returns zero,
b8a0: 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20   the custom VFS 
b8b0: 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74  should abandon t
b8c0: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70  he.** current op
b8d0: 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c  eration..**.** <
b8e0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b8f0: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d  L_TEMPFILENAME]]
b900: 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e  .** ^Application
b910: 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20   can invoke the 
b920: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
b930: 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65  MPFILENAME] file
b940: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68  -control.** to h
b950: 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72  ave SQLite gener
b960: 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61  ate a.** tempora
b970: 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e  ry filename usin
b980: 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
b990: 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c  ithm that is fol
b9a0: 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74  lowed to generat
b9b0: 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
b9c0: 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d  ilenames for TEM
b9d0: 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68  P tables and oth
b9e0: 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73  er internal uses
b9f0: 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65  .  The.** argume
ba00: 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63  nt should be a c
ba10: 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c  har** which will
ba20: 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20   be filled with 
ba30: 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  the filename.** 
ba40: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
ba50: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
ba60: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
ba70: 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65  c()].  The calle
ba80: 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f  r should.** invo
ba90: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ke [sqlite3_free
baa0: 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c  ()] on the resul
bab0: 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d  t to avoid a mem
bac0: 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20  ory leak..**.** 
bad0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
bae0: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a  TL_MMAP_SIZE]].*
baf0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
bb00: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66  NTL_MMAP_SIZE] f
bb10: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
bb20: 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20  sed to query or 
bb30: 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d  set the.** maxim
bb40: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  um number of byt
bb50: 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20  es that will be 
bb60: 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d  used for memory-
bb70: 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54  mapped I/O..** T
bb80: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
bb90: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
bba0: 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69  lue of type sqli
bbb0: 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a  te3_int64 that.*
bbc0: 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79  * is an advisory
bbd0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
bbe0: 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
bbf0: 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d  file to memory m
bc00: 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e  ap.  The.** poin
bc10: 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74  ter is overwritt
bc20: 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20  en with the old 
bc30: 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69  value.  The limi
bc40: 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  t is not changed
bc50: 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65   if.** the value
bc60: 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e   originally poin
bc70: 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69  ted to is negati
bc80: 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63  ve, and so the c
bc90: 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a  urrent limit .**
bca0: 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20   can be queried 
bcb0: 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20  by passing in a 
bcc0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67  pointer to a neg
bcd0: 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54  ative number.  T
bce0: 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74  his.** file-cont
bcf0: 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65  rol is used inte
bd00: 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d  rnally to implem
bd10: 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  ent [PRAGMA mmap
bd20: 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  _size]..**.** <l
bd30: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bd40: 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20  _TRACE]].** The 
bd50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
bd60: 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ACE] file contro
bd70: 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73  l provides advis
bd80: 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ory information.
bd90: 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62  ** to the VFS ab
bda0: 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67  out what the hig
bdb0: 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68  her layers of th
bdc0: 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61  e SQLite stack a
bdd0: 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69  re doing..** Thi
bde0: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
bdf0: 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56  s used by some V
be00: 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63  FS activity trac
be10: 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20  ing [shims]..** 
be20: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
be30: 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
be40: 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65  d string.  Highe
be50: 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a  r layers in the.
be60: 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  ** SQLite stack 
be70: 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73  may generate ins
be80: 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66  tances of this f
be90: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a  ile control if.*
bea0: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  * the [SQLITE_US
beb0: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63  E_FCNTL_TRACE] c
bec0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
bed0: 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
bee0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
bef0: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
bf00: 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  D]].** The [SQLI
bf10: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
bf20: 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ED] file control
bf30: 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20   interprets its 
bf40: 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a  argument as a.**
bf50: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
bf60: 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72  nteger and it wr
bf70: 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69  ites a boolean i
bf80: 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72  nto that integer
bf90: 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e   depending.** on
bfa0: 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
bfb0: 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65  the file has bee
bfc0: 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64  n renamed, moved
bfd0: 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e  , or deleted sin
bfe0: 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72  ce it.** was fir
bff0: 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a  st opened..**.**
c000: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c010: 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41  NTL_WIN32_GET_HA
c020: 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NDLE]].** The [S
c030: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
c040: 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70  2_GET_HANDLE] op
c050: 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64  code can be used
c060: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a   to obtain the.*
c070: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74  * underlying nat
c080: 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  ive file handle 
c090: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
c0a0: 61 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20  a file handle.  
c0b0: 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e  This file.** con
c0c0: 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20  trol interprets 
c0d0: 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20  its argument as 
c0e0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
c0f0: 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c  ative file handl
c100: 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20  e and.** writes 
c110: 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 76 61  the resulting va
c120: 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  lue there..**.**
c130: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c140: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41  NTL_WIN32_SET_HA
c150: 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NDLE]].** The [S
c160: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
c170: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70  2_SET_HANDLE] op
c180: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
c190: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
c1a0: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
c1b0: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
c1c0: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77  rol method to sw
c1d0: 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64  ap the file hand
c1e0: 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a  le with the one.
c1f0: 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
c200: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
c210: 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69  nt.  This capabi
c220: 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72  lity is used dur
c230: 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61  ing testing.** a
c240: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  nd only needs to
c250: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68   be supported wh
c260: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69  en SQLITE_TEST i
c270: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  s defined..**.**
c280: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c290: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a  NTL_WAL_BLOCK]].
c2a0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
c2b0: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20  CNTL_WAL_BLOCK] 
c2c0: 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74  is a signal to t
c2d0: 68 65 20 56 46 53 20 6c 61 79 65 72 20 74 68 61  he VFS layer tha
c2e0: 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65  t it might.** be
c2f0: 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f   advantageous to
c300: 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65   block on the ne
c310: 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74  xt WAL lock if t
c320: 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69  he lock is not i
c330: 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76  mmediately.** av
c340: 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41  ailable.  The WA
c350: 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73 73 75  L subsystem issu
c360: 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64  es this signal d
c370: 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69  uring rare.** ci
c380: 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f  rcumstances in o
c390: 72 64 65 72 20 74 6f 20 66 69 78 20 61 20 70 72  rder to fix a pr
c3a0: 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72  oblem with prior
c3b0: 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ity inversion..*
c3c0: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
c3d0: 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65  hould <em>not</e
c3e0: 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c 65  m> use this file
c3f0: 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  -control..**.** 
c400: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
c410: 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54  TL_ZIPVFS]].** T
c420: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
c430: 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20  _ZIPVFS] opcode 
c440: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  is implemented b
c450: 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41  y zipvfs only. A
c460: 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20  ll other.** VFS 
c470: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51  should return SQ
c480: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f  LITE_NOTFOUND fo
c490: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a  r this opcode..*
c4a0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
c4b0: 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a  E_FCNTL_RBU]].**
c4c0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
c4d0: 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69  TL_RBU] opcode i
c4e0: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79  s implemented by
c4f0: 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53   the special VFS
c500: 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20   used by.** the 
c510: 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e  RBU extension on
c520: 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56  ly.  All other V
c530: 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  FS should return
c540: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
c550: 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63   for.** this opc
c560: 6f 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ode.  .**.** <li
c570: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
c580: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49  BEGIN_ATOMIC_WRI
c590: 54 45 5d 5d 0a 2a 2a 20 49 66 20 74 68 65 20 5b  TE]].** If the [
c5a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
c5b0: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
c5c0: 20 6f 70 63 6f 64 65 20 72 65 74 75 72 6e 73 20   opcode returns 
c5d0: 53 51 4c 49 54 45 5f 4f 4b 2c 20 74 68 65 6e 0a  SQLITE_OK, then.
c5e0: 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73 63  ** the file desc
c5f0: 72 69 70 74 6f 72 20 69 73 20 70 6c 61 63 65 64  riptor is placed
c600: 20 69 6e 20 22 62 61 74 63 68 20 77 72 69 74 65   in "batch write
c610: 20 6d 6f 64 65 22 2c 20 77 68 69 63 68 0a 2a 2a   mode", which.**
c620: 20 6d 65 61 6e 73 20 61 6c 6c 20 73 75 62 73 65   means all subse
c630: 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65 72  quent write oper
c640: 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 20 64  ations will be d
c650: 65 66 65 72 72 65 64 20 61 6e 64 20 64 6f 6e 65  eferred and done
c660: 0a 2a 2a 20 61 74 6f 6d 69 63 61 6c 6c 79 20 61  .** atomically a
c670: 74 20 74 68 65 20 6e 65 78 74 20 5b 53 51 4c 49  t the next [SQLI
c680: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
c690: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 20 20  ATOMIC_WRITE].  
c6a0: 53 79 73 74 65 6d 73 0a 2a 2a 20 74 68 61 74 20  Systems.** that 
c6b0: 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 62  do not support b
c6c0: 61 74 63 68 20 61 74 6f 6d 69 63 20 77 72 69 74  atch atomic writ
c6d0: 65 73 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  es will return S
c6e0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 2e 0a  QLITE_NOTFOUND..
c6f0: 2a 2a 20 5e 46 6f 6c 6c 6f 77 69 6e 67 20 61 20  ** ^Following a 
c700: 73 75 63 63 65 73 73 66 75 6c 20 53 51 4c 49 54  successful SQLIT
c710: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54  E_FCNTL_BEGIN_AT
c720: 4f 4d 49 43 5f 57 52 49 54 45 20 61 6e 64 20 70  OMIC_WRITE and p
c730: 72 69 6f 72 20 74 6f 0a 2a 2a 20 74 68 65 20 63  rior to.** the c
c740: 6c 6f 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46  losing [SQLITE_F
c750: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d  CNTL_COMMIT_ATOM
c760: 49 43 5f 57 52 49 54 45 5d 20 6f 72 0a 2a 2a 20  IC_WRITE] or.** 
c770: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f  [SQLITE_FCNTL_RO
c780: 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52  LLBACK_ATOMIC_WR
c790: 49 54 45 5d 2c 20 53 51 4c 69 74 65 20 77 69 6c  ITE], SQLite wil
c7a0: 6c 20 6d 61 6b 65 0a 2a 2a 20 6e 6f 20 56 46 53  l make.** no VFS
c7b0: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 73   interface calls
c7c0: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 73 71   on the same [sq
c7d0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 66 69 6c 65  lite3_file] file
c7e0: 20 64 65 73 63 72 69 70 74 6f 72 0a 2a 2a 20 65   descriptor.** e
c7f0: 78 63 65 70 74 20 66 6f 72 20 63 61 6c 6c 73 20  xcept for calls 
c800: 74 6f 20 74 68 65 20 78 57 72 69 74 65 20 6d 65  to the xWrite me
c810: 74 68 6f 64 20 61 6e 64 20 74 68 65 20 78 46 69  thod and the xFi
c820: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
c830: 0a 2a 2a 20 77 69 74 68 20 5b 53 51 4c 49 54 45  .** with [SQLITE
c840: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
c850: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
c860: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
c870: 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IT_ATOMIC_WRITE]
c880: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
c890: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54  _FCNTL_COMMIT_AT
c8a0: 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f  OMIC_WRITE] opco
c8b0: 64 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72  de causes all wr
c8c0: 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e  ite.** operation
c8d0: 73 20 73 69 6e 63 65 20 74 68 65 20 70 72 65 76  s since the prev
c8e0: 69 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c 20  ious successful 
c8f0: 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c  call to .** [SQL
c900: 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f  ITE_FCNTL_BEGIN_
c910: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f  ATOMIC_WRITE] to
c920: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 61 74   be performed at
c930: 6f 6d 69 63 61 6c 6c 79 2e 0a 2a 2a 20 54 68 69  omically..** Thi
c940: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  s file control r
c950: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
c960: 4b 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  K] if and only i
c970: 66 20 74 68 65 20 77 72 69 74 65 73 20 77 65 72  f the writes wer
c980: 65 0a 2a 2a 20 61 6c 6c 20 70 65 72 66 6f 72 6d  e.** all perform
c990: 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  ed successfully 
c9a0: 61 6e 64 20 68 61 76 65 20 62 65 65 6e 20 63 6f  and have been co
c9b0: 6d 6d 69 74 74 65 64 20 74 6f 20 70 65 72 73 69  mmitted to persi
c9c0: 73 74 65 6e 74 20 73 74 6f 72 61 67 65 2e 0a 2a  stent storage..*
c9d0: 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66  * ^Regardless of
c9e0: 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
c9f0: 69 74 20 69 73 20 73 75 63 63 65 73 73 66 75 6c  it is successful
ca00: 2c 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74  , this file cont
ca10: 72 6f 6c 20 74 61 6b 65 73 0a 2a 2a 20 74 68 65  rol takes.** the
ca20: 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72   file descriptor
ca30: 20 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77 72   out of batch wr
ca40: 69 74 65 20 6d 6f 64 65 20 73 6f 20 74 68 61 74  ite mode so that
ca50: 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a   all subsequent.
ca60: 2a 2a 20 77 72 69 74 65 20 6f 70 65 72 61 74 69  ** write operati
ca70: 6f 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e 64  ons are independ
ca80: 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ent..** ^SQLite 
ca90: 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
caa0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
cab0: 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49  OMMIT_ATOMIC_WRI
cac0: 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20  TE without.** a 
cad0: 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
cae0: 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45   call to [SQLITE
caf0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
cb00: 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a  MIC_WRITE]..**.*
cb10: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
cb20: 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54  CNTL_ROLLBACK_AT
cb30: 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20  OMIC_WRITE]].** 
cb40: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
cb50: 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49  L_ROLLBACK_ATOMI
cb60: 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  C_WRITE] opcode 
cb70: 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74 65  causes all write
cb80: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20 73  .** operations s
cb90: 69 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f 75  ince the previou
cba0: 73 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  s successful cal
cbb0: 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  l to .** [SQLITE
cbc0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
cbd0: 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62 65  MIC_WRITE] to be
cbe0: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
cbf0: 20 5e 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74   ^This file cont
cc00: 72 6f 6c 20 74 61 6b 65 73 20 74 68 65 20 66 69  rol takes the fi
cc10: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20 6f 75  le descriptor ou
cc20: 74 20 6f 66 20 62 61 74 63 68 20 77 72 69 74 65  t of batch write
cc30: 20 6d 6f 64 65 0a 2a 2a 20 73 6f 20 74 68 61 74   mode.** so that
cc40: 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
cc50: 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  write operations
cc60: 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65 6e 74   are independent
cc70: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
cc80: 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 53  l never invoke S
cc90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c  QLITE_FCNTL_ROLL
cca0: 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54  BACK_ATOMIC_WRIT
ccb0: 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70  E without.** a p
ccc0: 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
ccd0: 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f  call to [SQLITE_
cce0: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
ccf0: 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a  IC_WRITE]..**.**
cd00: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
cd10: 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54  NTL_LOCK_TIMEOUT
cd20: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
cd30: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d  E_FCNTL_LOCK_TIM
cd40: 45 4f 55 54 5d 20 6f 70 63 6f 64 65 20 63 61 75  EOUT] opcode cau
cd50: 73 65 73 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ses attempts to 
cd60: 6f 62 74 61 69 6e 0a 2a 2a 20 61 20 66 69 6c 65  obtain.** a file
cd70: 20 6c 6f 63 6b 20 75 73 69 6e 67 20 74 68 65 20   lock using the 
cd80: 78 4c 6f 63 6b 20 6f 72 20 78 53 68 6d 4c 6f 63  xLock or xShmLoc
cd90: 6b 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65  k methods of the
cda0: 20 56 46 53 20 74 6f 20 77 61 69 74 0a 2a 2a 20   VFS to wait.** 
cdb0: 66 6f 72 20 75 70 20 74 6f 20 4d 20 6d 69 6c 6c  for up to M mill
cdc0: 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20  iseconds before 
cdd0: 66 61 69 6c 69 6e 67 2c 20 77 68 65 72 65 20 4d  failing, where M
cde0: 20 69 73 20 74 68 65 20 73 69 6e 67 6c 65 20 0a   is the single .
cdf0: 2a 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  ** unsigned inte
ce00: 67 65 72 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ger parameter..*
ce10: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </ul>.*/.#defi
ce20: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
ce30: 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20  LOCKSTATE       
ce40: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
ce50: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47  e SQLITE_FCNTL_G
ce60: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
ce70: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
ce80: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45   SQLITE_FCNTL_SE
ce90: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
cea0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
ceb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53  SQLITE_FCNTL_LAS
cec0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
ced0: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
cee0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
cef0: 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  _HINT           
cf00: 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
cf10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
cf20: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  _SIZE           
cf30: 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
cf40: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
cf50: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20  OINTER          
cf60: 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
cf70: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
cf80: 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20  ITTED           
cf90: 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
cfa0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
cfb0: 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20  _RETRY          
cfc0: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
cfd0: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
cfe0: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30  AL            10
cff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d000: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20  FCNTL_OVERWRITE 
d010: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a               11.
d020: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d030: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20  CNTL_VFSNAME    
d040: 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23              12.#
d050: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d060: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
d070: 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64  ERWRITE    13.#d
d080: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d090: 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TL_PRAGMA       
d0a0: 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65            14.#de
d0b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d0c0: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20  L_BUSYHANDLER   
d0d0: 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66           15.#def
d0e0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d0f0: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20  _TEMPFILENAME   
d100: 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69          16.#defi
d110: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d120: 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20  MMAP_SIZE       
d130: 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e         18.#defin
d140: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
d150: 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20  RACE            
d160: 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65        19.#define
d170: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41   SQLITE_FCNTL_HA
d180: 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20  S_MOVED         
d190: 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20       20.#define 
d1a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
d1b0: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
d1c0: 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53      21.#define S
d1d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
d1e0: 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20  IT_PHASETWO     
d1f0: 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51     22.#define SQ
d200: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
d210: 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20  _SET_HANDLE     
d220: 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c    23.#define SQL
d230: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
d240: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  OCK             
d250: 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   24.#define SQLI
d260: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20  TE_FCNTL_ZIPVFS 
d270: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d280: 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  25.#define SQLIT
d290: 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20  E_FCNTL_RBU     
d2a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
d2b0: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
d2c0: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
d2d0: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 32 37  ER            27
d2e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d2f0: 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f  FCNTL_JOURNAL_PO
d300: 49 4e 54 45 52 20 20 20 20 20 20 20 20 32 38 0a  INTER        28.
d310: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d320: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
d330: 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a 23  ANDLE       29.#
d340: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d350: 4e 54 4c 5f 50 44 42 20 20 20 20 20 20 20 20 20  NTL_PDB         
d360: 20 20 20 20 20 20 20 20 20 20 20 33 30 0a 23 64             30.#d
d370: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d380: 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f  TL_BEGIN_ATOMIC_
d390: 57 52 49 54 45 20 20 20 20 20 33 31 0a 23 64 65  WRITE     31.#de
d3a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d3b0: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
d3c0: 57 52 49 54 45 20 20 20 20 33 32 0a 23 64 65 66  WRITE    32.#def
d3d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d3e0: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
d3f0: 5f 57 52 49 54 45 20 20 33 33 0a 23 64 65 66 69  _WRITE  33.#defi
d400: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d410: 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54 20 20 20 20  LOCK_TIMEOUT    
d420: 20 20 20 20 20 20 20 33 34 0a 0a 2f 2a 20 64 65         34../* de
d430: 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a  precated names *
d440: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d450: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
d460: 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46  LE      SQLITE_F
d470: 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_GET_LOCKPRO
d480: 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53  XYFILE.#define S
d490: 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52  QLITE_SET_LOCKPR
d4a0: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c  OXYFILE      SQL
d4b0: 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f  ITE_FCNTL_SET_LO
d4c0: 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66  CKPROXYFILE.#def
d4d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f  ine SQLITE_LAST_
d4e0: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
d4f0: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c    SQLITE_FCNTL_L
d500: 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a  AST_ERRNO.../*.*
d510: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
d520: 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54  x Handle.**.** T
d530: 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20  he mutex module 
d540: 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65  within SQLite de
d550: 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d  fines [sqlite3_m
d560: 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a  utex] to be an.*
d570: 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20  * abstract type 
d580: 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65  for a mutex obje
d590: 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  ct.  The SQLite 
d5a0: 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73  core never looks
d5b0: 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72  .** at the inter
d5c0: 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
d5d0: 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  on of an [sqlite
d5e0: 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e  3_mutex].  It on
d5f0: 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68  ly.** deals with
d600: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
d610: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
d620: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d   object..**.** M
d630: 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74  utexes are creat
d640: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
d650: 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d  3_mutex_alloc()]
d660: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
d670: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  uct sqlite3_mute
d680: 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b  x sqlite3_mutex;
d690: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
d6a0: 3a 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e  : Loadable Exten
d6b0: 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a  sion Thunk.**.**
d6c0: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   A pointer to th
d6d0: 65 20 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33  e opaque sqlite3
d6e0: 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74  _api_routines st
d6f0: 72 75 63 74 75 72 65 20 69 73 20 70 61 73 73 65  ructure is passe
d700: 64 20 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72  d as.** the thir
d710: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65  d parameter to e
d720: 6e 74 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b  ntry points of [
d730: 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69  loadable extensi
d740: 6f 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73  ons].  This.** s
d750: 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 62 65  tructure must be
d760: 20 74 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72   typedefed in or
d770: 64 65 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  der to work arou
d780: 6e 64 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e  nd compiler warn
d790: 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20  ings.** on some 
d7a0: 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79  platforms..*/.ty
d7b0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
d7c0: 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65  ite3_api_routine
d7d0: 73 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f  s sqlite3_api_ro
d7e0: 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43  utines;../*.** C
d7f0: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
d800: 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a  rface Object.**.
d810: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
d820: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
d830: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
d840: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
d850: 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51  etween.** the SQ
d860: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68  Lite core and th
d870: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
d880: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
d890: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20  The "vfs".** in 
d8a0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
d8b0: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f  object stands fo
d8c0: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20  r "virtual file 
d8d0: 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a  system".  See.**
d8e0: 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20   the [VFS | VFS 
d8f0: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
d900: 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72  or further infor
d910: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
d920: 65 20 56 46 53 20 69 6e 74 65 72 66 61 63 65 20  e VFS interface 
d930: 69 73 20 73 6f 6d 65 74 69 6d 65 73 20 65 78 74  is sometimes ext
d940: 65 6e 64 65 64 20 62 79 20 61 64 64 69 6e 67 20  ended by adding 
d950: 6e 65 77 20 6d 65 74 68 6f 64 73 20 6f 6e 74 6f  new methods onto
d960: 0a 2a 2a 20 74 68 65 20 65 6e 64 2e 20 20 45 61  .** the end.  Ea
d970: 63 68 20 74 69 6d 65 20 73 75 63 68 20 61 6e 20  ch time such an 
d980: 65 78 74 65 6e 73 69 6f 6e 20 6f 63 63 75 72 73  extension occurs
d990: 2c 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  , the iVersion f
d9a0: 69 65 6c 64 0a 2a 2a 20 69 73 20 69 6e 63 72 65  ield.** is incre
d9b0: 6d 65 6e 74 65 64 2e 20 20 54 68 65 20 69 56 65  mented.  The iVe
d9c0: 72 73 69 6f 6e 20 76 61 6c 75 65 20 73 74 61 72  rsion value star
d9d0: 74 65 64 20 6f 75 74 20 61 73 20 31 20 69 6e 0a  ted out as 1 in.
d9e0: 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69  ** SQLite [versi
d9f0: 6f 6e 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b 64 61  on 3.5.0] on [da
da00: 74 65 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74 68 65  teof:3.5.0], the
da10: 6e 20 69 6e 63 72 65 61 73 65 64 20 74 6f 20 32  n increased to 2
da20: 0a 2a 2a 20 77 69 74 68 20 53 51 4c 69 74 65 20  .** with SQLite 
da30: 5b 76 65 72 73 69 6f 6e 20 33 2e 37 2e 30 5d 20  [version 3.7.0] 
da40: 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e 30  on [dateof:3.7.0
da50: 5d 2c 20 61 6e 64 20 74 68 65 6e 20 69 6e 63 72  ], and then incr
da60: 65 61 73 65 64 0a 2a 2a 20 74 6f 20 33 20 77 69  eased.** to 3 wi
da70: 74 68 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69  th SQLite [versi
da80: 6f 6e 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b 64 61  on 3.7.6] on [da
da90: 74 65 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20 41 64  teof:3.7.6].  Ad
daa0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
dab0: 2a 2a 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ** may be append
dac0: 65 64 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  ed to the sqlite
dad0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 61 6e 64  3_vfs object and
dae0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
daf0: 6c 75 65 0a 2a 2a 20 6d 61 79 20 69 6e 63 72 65  lue.** may incre
db00: 61 73 65 20 61 67 61 69 6e 20 69 6e 20 66 75 74  ase again in fut
db10: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
db20: 53 51 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74 65 20  SQLite..** Note 
db30: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
db40: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
db50: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
db60: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
db70: 72 61 6e 73 69 74 69 6f 6e 20 66 72 6f 6d 0a 2a  ransition from.*
db80: 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f  * SQLite [versio
db90: 6e 20 33 2e 35 2e 39 5d 20 74 6f 20 5b 76 65 72  n 3.5.9] to [ver
dba0: 73 69 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e 20 5b  sion 3.6.0] on [
dbb0: 64 61 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a 2a 2a  dateof:3.6.0].**
dbc0: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
dbd0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
dbe0: 6e 6f 74 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  not modified..**
dbf0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
dc00: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
dc10: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
dc20: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
dc30: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
dc40: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
dc50: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
dc60: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
dc70: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
dc80: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
dc90: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
dca0: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
dcb0: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
dcc0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
dcd0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
dce0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
dcf0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
dd00: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
dd10: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
dd20: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
dd30: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
dd40: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
dd50: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
dd60: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
dd70: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
dd80: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
dd90: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
dda0: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
ddb0: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
ddc0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
ddd0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
dde0: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
ddf0: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
de00: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
de10: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
de20: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
de30: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
de40: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
de50: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
de60: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
de70: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
de80: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
de90: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
dea0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
deb0: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
dec0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
ded0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
dee0: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
def0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
df00: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
df10: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
df20: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
df30: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
df40: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
df50: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
df60: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
df70: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
df80: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
df90: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
dfa0: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
dfb0: 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c  .xOpen]].** ^SQL
dfc0: 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
dfd0: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
dfe0: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
dff0: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
e000: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
e010: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
e020: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
e030: 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68  lPathname() with
e040: 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66   an optional suf
e050: 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49  fix added..** ^I
e060: 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64  f a suffix is ad
e070: 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65  ded to the zFile
e080: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20  name parameter, 
e090: 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69  it will.** consi
e0a0: 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22  st of a single "
e0b0: 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c  -" character fol
e0c0: 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65  lowed by no more
e0d0: 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68   than.** 11 alph
e0e0: 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20  anumeric and/or 
e0f0: 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a  "-" characters..
e100: 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68  ** ^SQLite furth
e110: 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  er guarantees th
e120: 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  at.** the string
e130: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
e140: 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74  nd unchanged unt
e150: 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a  il xClose() is.*
e160: 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73  * called. Becaus
e170: 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75  e of the previou
e180: 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74  s sentence,.** t
e190: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
e1a0: 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f  ] can safely sto
e1b0: 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  re a pointer to 
e1c0: 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  the.** filename 
e1d0: 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72  if it needs to r
e1e0: 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65  emember the file
e1f0: 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65  name for some re
e200: 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ason..** If the 
e210: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
e220: 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20  ter to xOpen is 
e230: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
e240: 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73  hen xOpen.** mus
e250: 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e  t invent its own
e260: 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20   temporary name 
e270: 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e  for the file.  ^
e280: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a  Whenever the .**
e290: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   xFilename param
e2a0: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20  eter is NULL it 
e2b0: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65  will also be the
e2c0: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a   case that the.*
e2d0: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  * flags paramete
e2e0: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b  r will include [
e2f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
e300: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a  TEONCLOSE]..**.*
e310: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
e320: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20  ment to xOpen() 
e330: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74  includes all bit
e340: 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20  s set in.** the 
e350: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
e360: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
e370: 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73  v2()].  Or if [s
e380: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
e390: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
e3a0: 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  en16()] is used,
e3b0: 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c   then flags incl
e3c0: 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a  udes at least.**
e3d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
e3e0: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
e3f0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
e400: 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20   .** If xOpen() 
e410: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
e420: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
e430: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
e440: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
e450: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
e460: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
e470: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
e480: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
e490: 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61   ^(SQLite will a
e4a0: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
e4b0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
e4c0: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28  gs to the xOpen(
e4d0: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e  ).** call, depen
e4e0: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65  ding on the obje
e4f0: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a  ct being opened:
e500: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
e510: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
e520: 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_MAIN_DB].** <l
e530: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
e540: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _MAIN_JOURNAL].*
e550: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
e560: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a  OPEN_TEMP_DB].**
e570: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
e580: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
e590: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
e5a0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
e5b0: 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  T_DB].** <li>  [
e5c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
e5d0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
e5e0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
e5f0: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  STER_JOURNAL].**
e600: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
e610: 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  PEN_WAL].** </ul
e620: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  >)^.**.** The fi
e630: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
e640: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
e650: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
e660: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
e670: 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c   the way it deal
e680: 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46  s with files.  F
e690: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  or example, an a
e6a0: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68  pplication.** th
e6b0: 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  at does not care
e6c0: 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63   about crash rec
e6d0: 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63  overy or rollbac
e6e0: 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20  k might make.** 
e6f0: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f  the open of a jo
e700: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d  urnal file a no-
e710: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  op.  Writes to t
e720: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  his journal woul
e730: 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d  d.** also be no-
e740: 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74  ops, and any att
e750: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65  empt to read the
e760: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72   journal would r
e770: 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
e780: 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69  IOERR.  Or the i
e790: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
e7a0: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
e7b0: 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  at a database.**
e7c0: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f   file will be do
e7d0: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
e7e0: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
e7f0: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
e800: 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  ndom.** order an
e810: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
e820: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
e830: 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51  dingly..**.** SQ
e840: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
e850: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
e860: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
e870: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
e880: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
e890: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
e8a0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
e8b0: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
e8c0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
e8d0: 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  E].** </ul>.**.*
e8e0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  * The [SQLITE_OP
e8f0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
e900: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
e910: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a   file should be.
e920: 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ** deleted when 
e930: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e  it is closed.  ^
e940: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
e950: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
e960: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66  ** will be set f
e970: 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65  or TEMP database
e980: 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72  s and their jour
e990: 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a  nals, transient.
e9a0: 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e  ** databases, an
e9b0: 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a  d subjournals..*
e9c0: 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
e9d0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
e9e0: 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73  ] flag is always
e9f0: 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63   used in conjunc
ea00: 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
ea10: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
ea20: 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63  EATE] flag, whic
ea30: 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63  h are both direc
ea40: 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73  tly.** analogous
ea50: 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61   to the O_EXCL a
ea60: 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73  nd O_CREAT flags
ea70: 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70   of the POSIX op
ea80: 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68  en().** API.  Th
ea90: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58  e SQLITE_OPEN_EX
eaa0: 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68  CLUSIVE flag, wh
eab0: 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74  en paired with t
eac0: 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50  he .** SQLITE_OP
ead0: 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73  EN_CREATE, is us
eae0: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
eaf0: 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  hat file should 
eb00: 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65  always.** be cre
eb10: 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69  ated, and that i
eb20: 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66  t is an error if
eb30: 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73   it already exis
eb40: 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e  ts..** It is <i>
eb50: 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20  not</i> used to 
eb60: 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c  indicate the fil
eb70: 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e  e should be open
eb80: 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75  ed .** for exclu
eb90: 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a  sive access..**.
eba0: 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f  ** ^At least szO
ebb0: 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d  sFile bytes of m
ebc0: 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61  emory are alloca
ebd0: 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  ted by SQLite.**
ebe0: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73   to hold the  [s
ebf0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72  qlite3_file] str
ec00: 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73  ucture passed as
ec10: 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   the third.** ar
ec20: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e  gument to xOpen.
ec30: 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68    The xOpen meth
ec40: 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  od does not have
ec50: 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20   to.** allocate 
ec60: 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69  the structure; i
ec70: 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69  t should just fi
ec80: 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20  ll it in.  Note 
ec90: 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65  that.** the xOpe
eca0: 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65  n method must se
ecb0: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
ecc0: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65  le.pMethods to e
ecd0: 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64  ither.** a valid
ece0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
ecf0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20  hods] object or 
ed00: 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20  to NULL.  xOpen 
ed10: 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20  must do.** this 
ed20: 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e  even if the open
ed30: 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20   fails.  SQLite 
ed40: 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65  expects that the
ed50: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
ed60: 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e  ethods.** elemen
ed70: 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  t will be valid 
ed80: 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75  after xOpen retu
ed90: 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f  rns regardless o
eda0: 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a  f the success.**
edb0: 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74   or failure of t
edc0: 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a  he xOpen call..*
edd0: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
ede0: 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20  fs.xAccess]].** 
edf0: 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d  ^The flags argum
ee00: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
ee10: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
ee20: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
ee30: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
ee40: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
ee50: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
ee60: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
ee70: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
ee80: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
ee90: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
eea0: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
eeb0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
eec0: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
eed0: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
eee0: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
eef0: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
ef00: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
ef10: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
ef20: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
ef30: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
ef40: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
ef50: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
ef60: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
ef70: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78  athname.  The ex
ef80: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
ef90: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
efa0: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
efb0: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
efc0: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
efd0: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
efe0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
eff0: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
f000: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
f010: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
f020: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
f030: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
f040: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
f050: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
f060: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
f070: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
f080: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
f090: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
f0a0: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
f0b0: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
f0c0: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
f0d0: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
f0e0: 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74  leep(), xCurrent
f0f0: 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72  Time(), and xCur
f100: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a  rentTimeInt64().
f110: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ** interfaces ar
f120: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
f130: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
f140: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
f150: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
f160: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
f170: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
f180: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
f190: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
f1a0: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
f1b0: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
f1c0: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
f1d0: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
f1e0: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
f1f0: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
f200: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
f210: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
f220: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
f230: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
f240: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
f250: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
f260: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
f270: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
f280: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
f290: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
f2a0: 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75  given.  ^The xCu
f2b0: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
f2c0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
f2d0: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
f2e0: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
f2f0: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  t date and time 
f300: 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67  as.** a floating
f310: 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a   point value..**
f320: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
f330: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
f340: 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20   returns, as an 
f350: 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c  integer, the Jul
f360: 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65  ian.** Day Numbe
f370: 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20  r multiplied by 
f380: 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75  86400000 (the nu
f390: 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
f3a0: 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34  onds in .** a 24
f3b0: 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a  -hour day).  .**
f3c0: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
f3d0: 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69  e the xCurrentTi
f3e0: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
f3f0: 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72   to get the curr
f400: 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20  ent.** date and 
f410: 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74  time if that met
f420: 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65  hod is available
f430: 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73   (if iVersion is
f440: 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65   2 or .** greate
f450: 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69  r and the functi
f460: 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
f470: 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c  t NULL) and will
f480: 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f   fall back.** to
f490: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
f4a0: 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  if xCurrentTimeI
f4b0: 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69  nt64() is unavai
f4c0: 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lable..**.** ^Th
f4d0: 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  e xSetSystemCall
f4e0: 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61  (), xGetSystemCa
f4f0: 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53  ll(), and xNestS
f500: 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65  ystemCall() inte
f510: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
f520: 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51  t used by the SQ
f530: 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73  Lite core.  Thes
f540: 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72  e optional inter
f550: 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
f560: 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46  ed.** by some VF
f570: 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74  Ses to facilitat
f580: 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65  e testing of the
f590: 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76   VFS code. By ov
f5a0: 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73  erriding .** sys
f5b0: 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66  tem calls with f
f5c0: 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69  unctions under i
f5d0: 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65  ts control, a te
f5e0: 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a  st program can.*
f5f0: 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74  * simulate fault
f600: 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64  s and error cond
f610: 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c  itions that woul
f620: 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64  d otherwise be d
f630: 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69  ifficult.** or i
f640: 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64  mpossible to ind
f650: 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66  uce.  The set of
f660: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68   system calls th
f670: 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  at can be overri
f680: 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66  dden.** varies f
f690: 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61  rom one VFS to a
f6a0: 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d  nother, and from
f6b0: 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20   one version of 
f6c0: 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20  the same VFS to 
f6d0: 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70  the.** next.  Ap
f6e0: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
f6f0: 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66  use these interf
f700: 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65  aces must be pre
f710: 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a  pared for any.**
f720: 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65   or all of these
f730: 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62   interfaces to b
f740: 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68  e NULL or for th
f750: 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20  eir behavior to 
f760: 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f  change.** from o
f770: 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  ne release to th
f780: 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  e next.  Applica
f790: 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61  tions must not a
f7a0: 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73  ttempt to access
f7b0: 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65  .** any of these
f7c0: 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20   methods if the 
f7d0: 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20  iVersion of the 
f7e0: 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e  VFS is less than
f7f0: 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73   3..*/.typedef s
f800: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
f810: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74  s sqlite3_vfs;.t
f820: 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
f830: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
f840: 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74  r)(void);.struct
f850: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
f860: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
f870: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
f880: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
f890: 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79  umber (currently
f8a0: 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f   3) */.  int szO
f8b0: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
f8c0: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
f8d0: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
f8e0: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
f8f0: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
f900: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
f910: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
f920: 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
f930: 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
f940: 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
f950: 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
f960: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
f970: 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
f980: 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
f990: 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
f9a0: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
f9b0: 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
f9c0: 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
f9d0: 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
f9e0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
f9f0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
fa00: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
fa10: 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
fa20: 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
fa30: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
fa40: 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
fa50: 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
fa60: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
fa70: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
fa80: 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
fa90: 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
faa0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
fab0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
fac0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
fad0: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
fae0: 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28  *xFullPathname)(
faf0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
fb00: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
fb10: 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20   int nOut, char 
fb20: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
fb30: 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74  (*xDlOpen)(sqlit
fb40: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
fb50: 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b  har *zFilename);
fb60: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72  .  void (*xDlErr
fb70: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
fb80: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
fb90: 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76  r *zErrMsg);.  v
fba0: 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28  oid (*(*xDlSym)(
fbb0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
fbc0: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
fbd0: 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b  zSymbol))(void);
fbe0: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
fbf0: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
fc00: 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
fc10: 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
fc20: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
fc30: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
fc40: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
fc50: 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
fc60: 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
fc70: 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
fc80: 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
fc90: 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
fca0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  *);.  int (*xGet
fcb0: 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74  LastError)(sqlit
fcc0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68  e3_vfs*, int, ch
fcd0: 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  ar *);.  /*.  **
fce0: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
fcf0: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
fd00: 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74  n 1 of the sqlit
fd10: 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a  e_vfs object.  *
fd20: 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  * definition.  T
fd30: 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77  hose that follow
fd40: 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65   are added in ve
fd50: 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72  rsion 2 or later
fd60: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43  .  */.  int (*xC
fd70: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29  urrentTimeInt64)
fd80: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73  (sqlite3_vfs*, s
fd90: 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a  qlite3_int64*);.
fda0: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
fdb0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
fdc0: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e  in versions 1 an
fdd0: 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74  d 2 of the sqlit
fde0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
fdf0: 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61  ** Those below a
fe00: 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  re for version 3
fe10: 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20   and greater..  
fe20: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53  */.  int (*xSetS
fe30: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
fe40: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
fe50: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
fe60: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
fe70: 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63  ;.  sqlite3_sysc
fe80: 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79  all_ptr (*xGetSy
fe90: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
fea0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
feb0: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f  ar *zName);.  co
fec0: 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78  nst char *(*xNex
fed0: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
fee0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
fef0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
ff00: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
ff10: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
ff20: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72  n versions 1 thr
ff30: 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71  ough 3 of the sq
ff40: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
ff50: 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73  .  ** New fields
ff60: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
ff70: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
ff80: 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69  ons.  The iVersi
ff90: 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69  on.  ** value wi
ffa0: 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65  ll increment whe
ffb0: 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65  never this happe
ffc0: 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ns. .  */.};../*
ffd0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
ffe0: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
fff0: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ess VFS method.*
10000 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
10010 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
10020 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
10030 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
10040 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
10050 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
10060 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
10070 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72  ect.  They deter
10080 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e  mine.** what kin
10090 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73  d of permissions
100a0 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
100b0 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66  hod is looking f
100c0 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  or..** With SQLI
100d0 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
100e0 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
100f0 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63  thod.** simply c
10100 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
10110 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a  e file exists..*
10120 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
10130 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20  CESS_READWRITE, 
10140 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
10150 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
10160 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64  ther the named d
10170 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68  irectory is both
10180 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
10190 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74  itable.** (in ot
101a0 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69  her words, if fi
101b0 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64  les can be added
101c0 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72  , removed, and r
101d0 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a  enamed within.**
101e0 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e   the directory).
101f0 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41  .** The SQLITE_A
10200 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
10210 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72  constant is curr
10220 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20  ently used only 
10230 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f  by the.** [temp_
10240 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
10250 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20  pragma], though 
10260 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67  this could chang
10270 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a  e in a future.**
10280 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
10290 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  te..** With SQLI
102a0 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20  TE_ACCESS_READ, 
102b0 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
102c0 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
102d0 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73  ther the file is
102e0 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
102f0 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
10300 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a  AD constant is.*
10310 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73  * currently unus
10320 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69  ed, though it mi
10330 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61  ght be used in a
10340 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
10350 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f  of.** SQLite..*/
10360 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10370 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
10380 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
10390 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
103a0 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62  TE 1   /* Used b
103b0 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74  y PRAGMA temp_st
103c0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f  ore_directory */
103d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
103e0 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
103f0 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a   2   /* Unused *
10400 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
10410 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
10420 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65   xShmLock VFS me
10430 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
10440 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
10450 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61  ts define the va
10460 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70  rious locking op
10470 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f  erations.** allo
10480 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c  wed by the xShmL
10490 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73  ock method of [s
104a0 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
104b0 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c  s].  The.** foll
104c0 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e  owing are the on
104d0 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61  ly legal combina
104e0 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74  tions of flags t
104f0 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63  o the.** xShmLoc
10500 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  k method:.**.** 
10510 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  <ul>.** <li>  SQ
10520 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
10530 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
10540 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
10550 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
10560 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
10570 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  E.** <li>  SQLIT
10580 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
10590 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
105a0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
105b0 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
105c0 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
105d0 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VE.** </ul>.**.*
105e0 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67  * When unlocking
105f0 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45  , the same SHARE
10600 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66  D or EXCLUSIVE f
10610 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70  lag must be supp
10620 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67  lied as.** was g
10630 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72  iven on the corr
10640 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20  esponding lock. 
10650 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d   .**.** The xShm
10660 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20  Lock method can 
10670 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
10680 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
10690 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74  SHARED or.** bet
106a0 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
106b0 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74  d EXCLUSIVE.  It
106c0 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69   cannot transiti
106d0 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45  on between SHARE
106e0 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49  D.** and EXCLUSI
106f0 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  VE..*/.#define S
10700 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
10710 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
10720 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
10730 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
10740 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48  ne SQLITE_SHM_SH
10750 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65  ARED       4.#de
10760 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
10770 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a  EXCLUSIVE    8..
10780 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10790 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b  Maximum xShmLock
107a0 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65   index.**.** The
107b0 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
107c0 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   on [sqlite3_io_
107d0 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65  methods] may use
107e0 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
107f0 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70  en 0 and this up
10800 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73  per bound as its
10810 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65   "offset" argume
10820 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  nt..** The SQLit
10830 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65  e core will neve
10840 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71  r attempt to acq
10850 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20  uire or release 
10860 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64  a.** lock outsid
10870 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a  e of this range.
10880 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10890 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20  E_SHM_NLOCK     
108a0 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     8.../*.** CAP
108b0 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a  I3REF: Initializ
108c0 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  e The SQLite Lib
108d0 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rary.**.** ^The 
108e0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
108f0 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
10900 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
10910 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
10920 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68   ^The sqlite3_sh
10930 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65  utdown() routine
10940 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  .** deallocates 
10950 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68  any resources th
10960 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65  at were allocate
10970 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  d by sqlite3_ini
10980 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68  tialize()..** Th
10990 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
109a0 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64   designed to aid
109b0 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74   in process init
109c0 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a  ialization and.*
109d0 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d  * shutdown on em
109e0 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20  bedded systems. 
109f0 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70   Workstation app
10a00 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a  lications using.
10a10 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c  ** SQLite normal
10a20 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ly do not need t
10a30 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  o invoke either 
10a40 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
10a50 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  s..**.** A call 
10a60 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
10a70 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65  alize() is an "e
10a80 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
10a90 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66  f it is.** the f
10aa0 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
10ab0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
10ac0 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67  s invoked during
10ad0 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
10ae0 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c  .** the process,
10af0 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65   or if it is the
10b00 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
10b10 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10b20 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66   is invoked.** f
10b30 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20  ollowing a call 
10b40 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
10b50 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61  own().  ^(Only a
10b60 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
10b70 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69  .** of sqlite3_i
10b80 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73  nitialize() does
10b90 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74   any initializat
10ba0 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ion.  All other 
10bb0 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72  calls.** are har
10bc0 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
10bd0 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
10be0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10bf0 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
10c00 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
10c10 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
10c20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
10c30 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65  shutdown() since
10c40 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
10c50 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20  3_initialize(). 
10c60 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66   ^(Only.** an ef
10c70 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20  fective call to 
10c80 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10c90 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e  () does any dein
10ca0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  itialization..**
10cb0 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64   All other valid
10cc0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
10cd0 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65  3_shutdown() are
10ce0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
10cf0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  .)^.**.** The sq
10d00 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10d10 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
10d20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20  threadsafe, but 
10d30 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10d40 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54  ().** is not.  T
10d50 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
10d60 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  own() interface 
10d70 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c  must only be cal
10d80 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69  led from a.** si
10d90 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c  ngle thread.  Al
10da0 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  l open [database
10db0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75   connections] mu
10dc0 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64  st be closed and
10dd0 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51   all.** other SQ
10de0 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d  Lite resources m
10df0 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  ust be deallocat
10e00 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f  ed prior to invo
10e10 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  king.** sqlite3_
10e20 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a  shutdown()..**.*
10e30 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68  * Among other th
10e40 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69  ings, ^sqlite3_i
10e50 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c  nitialize() will
10e60 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
10e70 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53  e3_os_init().  S
10e80 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74  imilarly, ^sqlit
10e90 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
10ea0 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c   will invoke sql
10eb0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a  ite3_os_end()..*
10ec0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
10ed0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
10ee0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
10ef0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
10f00 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f  ccess..** ^If fo
10f10 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73  r some reason, s
10f20 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10f30 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  e() is unable to
10f40 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74   initialize.** t
10f50 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68  he library (perh
10f60 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65  aps it is unable
10f70 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e   to allocate a n
10f80 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73  eeded resource s
10f90 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65  uch.** as a mute
10fa0 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e  x) it returns an
10fb0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74   [error code] ot
10fc0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
10fd0 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _OK]..**.** ^The
10fe0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10ff0 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
11000 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
11010 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
11020 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
11030 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
11040 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
11050 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
11060 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
11070 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11080 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
11090 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
110a0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
110b0 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
110c0 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
110d0 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
110e0 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
110f0 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
11100 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
11110 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
11120 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
11130 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
11140 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
11150 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51   ^However, if SQ
11160 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11170 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
11180 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
11190 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
111a0 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
111b0 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
111c0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
111d0 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
111e0 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
111f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
11200 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
11210 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
11220 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
11230 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
11240 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
11250 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
11260 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
11270 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
11280 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
11290 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
112a0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
112b0 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
112c0 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
112d0 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
112e0 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
112f0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
11300 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
11310 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
11320 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
11330 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
11340 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
11350 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11360 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d   with [SQLITE_OM
11370 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67  IT_AUTOINIT] mig
11380 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a  ht become the.**
11390 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
113a0 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  r in some future
113b0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
113c0 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te..**.** The sq
113d0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
113e0 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65  routine does ope
113f0 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
11400 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61  ecific.** initia
11410 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  lization of the 
11420 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
11430 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
11440 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  end().** routine
11450 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
11460 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  ct of sqlite3_os
11470 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61  _init().  Typica
11480 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f  l tasks.** perfo
11490 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f  rmed by these ro
114a0 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61  utines include a
114b0 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61  llocation or dea
114c0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
114d0 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73  static resources
114e0 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  , initialization
114f0 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61   of global varia
11500 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67  bles,.** setting
11510 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73   up a default [s
11520 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75  qlite3_vfs] modu
11530 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75  le, or setting u
11540 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63  p.** a default c
11550 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69  onfiguration usi
11560 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ng [sqlite3_conf
11570 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ig()]..**.** The
11580 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
11590 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  uld never invoke
115a0 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
115b0 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20  os_init().** or 
115c0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
115d0 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20   directly.  The 
115e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
115f0 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a  ld only invoke.*
11600 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
11610 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lize() and sqlit
11620 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
11630 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
11640 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  nit().** interfa
11650 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74  ce is called aut
11660 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
11670 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11680 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  () and.** sqlite
11690 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
116a0 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
116b0 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
116c0 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
116d0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
116e0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
116f0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
11700 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
11710 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
11720 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
11730 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69  led for Unix, Wi
11740 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a  ndows, or OS/2..
11750 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20  ** When [custom 
11760 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66  builds | built f
11770 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72  or other platfor
11780 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68  ms].** (using th
11790 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48  e [SQLITE_OS_OTH
117a0 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ER=1] compile-ti
117b0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
117c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
117d0 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
117e0 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
117f0 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
11800 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
11810 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
11820 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
11830 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
11840 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
11850 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
11860 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
11870 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
11880 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
11890 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
118a0 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
118b0 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
118c0 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74   failure..*/.int
118d0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
118e0 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ize(void);.int s
118f0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11900 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
11910 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
11920 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
11930 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
11940 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
11950 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
11960 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
11970 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
11980 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
11990 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
119a0 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
119b0 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
119c0 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
119d0 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
119e0 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
119f0 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
11a00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
11a10 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
11a20 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
11a30 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
11a40 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
11a50 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
11a60 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
11a70 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
11a80 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
11a90 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
11aa0 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
11ab0 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
11ac0 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68  eds..**.** <b>Th
11ad0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
11ae0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
11af0 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20  not threadsafe. 
11b00 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
11b10 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74  ** must ensure t
11b20 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
11b30 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
11b40 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
11b50 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
11b60 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
11b70 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
11b80 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  .</b>.**.** The 
11b90 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11ba0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61   interface.** ma
11bb0 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
11bc0 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
11bd0 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
11be0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
11bf0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11c00 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
11c10 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
11c20 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
11c30 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ^If sqlite3_conf
11c40 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ig() is called a
11c50 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e  fter [sqlite3_in
11c60 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20  itialize()] and 
11c70 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  before.** [sqlit
11c80 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74  e3_shutdown()] t
11c90 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75  hen it will retu
11ca0 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
11cb0 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76  ..** Note, howev
11cc0 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65  er, that ^sqlite
11cd0 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62  3_config() can b
11ce0 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74  e called as part
11cf0 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   of the.** imple
11d00 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  mentation of an 
11d10 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
11d20 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f  ned [sqlite3_os_
11d30 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  init()]..**.** T
11d40 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
11d50 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  t to sqlite3_con
11d60 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65  fig() is an inte
11d70 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72  ger.** [configur
11d80 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68  ation option] th
11d90 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
11da0 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f   what property o
11db0 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62  f SQLite is to b
11dc0 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53  e configured.  S
11dd0 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
11de0 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65  nts.** vary depe
11df0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f  nding on the [co
11e00 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11e10 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
11e20 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
11e30 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66  .** ^When a conf
11e40 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11e50 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33   is set, sqlite3
11e60 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
11e70 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
11e80 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  * ^If the option
11e90 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
11ea0 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
11eb0 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
11ec0 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
11ed0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
11ee0 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
11ef0 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73   code]..*/.int s
11f00 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
11f10 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
11f20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
11f30 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ure database con
11f40 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48  nections.** METH
11f50 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
11f60 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
11f70 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
11f80 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
11f90 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ake configuratio
11fa0 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
11fb0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
11fc0 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e  ection].  The in
11fd0 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c  terface is simil
11fe0 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ar to.** [sqlite
11ff0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65  3_config()] exce
12000 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e  pt that the chan
12010 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73  ges apply to a s
12020 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61  ingle.** [databa
12030 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
12040 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
12050 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29   first argument)
12060 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
12070 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
12080 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
12090 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
120a0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43  e.** [SQLITE_DBC
120b0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
120c0 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
120d0 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67  verb] - an integ
120e0 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74  er code .** that
120f0 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20   indicates what 
12100 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64  aspect of the [d
12110 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12120 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e  on] is being con
12130 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73  figured..** Subs
12140 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
12150 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
12160 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  on the configura
12170 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a  tion verb..**.**
12180 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
12190 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72  e3_db_config() r
121a0 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
121b0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
121c0 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f  * the call is co
121d0 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73  nsidered success
121e0 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
121f0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
12200 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
12210 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
12220 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
12230 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
12240 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  s.**.** An insta
12250 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
12260 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
12270 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
12280 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c   SQLite.** and l
12290 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
122a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
122b0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  nes..**.** This 
122c0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69  object is used i
122d0 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65  n only one place
122e0 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69   in the SQLite i
122f0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70  nterface..** A p
12300 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
12310 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
12320 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75  ject is the argu
12330 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ment to.** [sqli
12340 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68  te3_config()] wh
12350 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  en the configura
12360 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  tion option is.*
12370 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
12380 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c  _MALLOC] or [SQL
12390 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
123a0 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63  LLOC].  .** By c
123b0 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61  reating an insta
123c0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
123d0 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e  ct.** and passin
123e0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
123f0 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
12400 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29  _CONFIG_MALLOC])
12410 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69  .** during confi
12420 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70  guration, an app
12430 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
12440 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
12450 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
12460 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
12470 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  em for SQLite to
12480 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
12490 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d  its.** dynamic m
124a0 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a  emory needs..**.
124b0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
124c0 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73  ite comes with s
124d0 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e  everal [built-in
124e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
124f0 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  rs].** that are 
12500 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61  perfectly adequa
12510 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77  te for the overw
12520 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79  helming majority
12530 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
12540 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69  .** and that thi
12550 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79  s object is only
12560 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e   useful to a tin
12570 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70  y minority of ap
12580 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69  plications.** wi
12590 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d  th specialized m
125a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
125b0 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20   requirements.  
125c0 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a  This object is.*
125d0 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69  * also used duri
125e0 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51  ng testing of SQ
125f0 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
12600 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
12610 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
12620 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
12630 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72   simulates memor
12640 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20  y out-of-memory 
12650 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a  conditions in.**
12660 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79   order to verify
12670 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63   that SQLite rec
12680 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79  overs gracefully
12690 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f   from such.** co
126a0 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nditions..**.** 
126b0 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65  The xMalloc, xRe
126c0 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65  alloc, and xFree
126d0 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f   methods must wo
126e0 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d  rk like the.** m
126f0 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63  alloc(), realloc
12700 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75  () and free() fu
12710 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65  nctions from the
12720 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
12730 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ary..** ^SQLite 
12740 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
12750 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
12760 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c  ent to.** xReall
12770 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76  oc is always a v
12780 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
12790 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
127a0 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a   xRoundup..**.**
127b0 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65   xSize should re
127c0 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74  turn the allocat
127d0 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d  ed size of a mem
127e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
127f0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
12800 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c  ained from xMall
12810 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20  oc or xRealloc. 
12820 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   The allocated s
12830 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ize.** is always
12840 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67   at least as big
12850 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65   as the requeste
12860 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62  d size but may b
12870 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20  e larger..**.** 
12880 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74  The xRoundup met
12890 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74  hod returns what
128a0 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c   would be the al
128b0 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a  located size of.
128c0 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ** a memory allo
128d0 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70  cation given a p
128e0 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73  articular reques
128f0 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20  ted size.  Most 
12900 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
12910 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65  tors round up me
12920 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
12930 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65   at least to the
12940 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a   next multiple.*
12950 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c  * of 8.  Some al
12960 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
12970 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75  p to a larger mu
12980 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70  ltiple or to a p
12990 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76  ower of 2..** Ev
129a0 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
129b0 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f  ation request co
129c0 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20  ming in through 
129d0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
129e0 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
129f0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72  3_realloc()] fir
12a00 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75  st calls xRoundu
12a10 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20  p.  If xRoundup 
12a20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74  returns 0, .** t
12a30 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63  hat causes the c
12a40 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d  orresponding mem
12a50 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
12a60 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o fail..**.** Th
12a70 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
12a80 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
12a90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
12aa0 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a    For example,.*
12ab0 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63  * it might alloc
12ac0 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20  ate any require 
12ad0 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69  mutexes or initi
12ae0 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64  alize internal d
12af0 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ata.** structure
12b00 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77  s.  The xShutdow
12b10 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  n method is invo
12b20 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29  ked (indirectly)
12b30 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
12b40 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20  shutdown()] and 
12b50 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74  should deallocat
12b60 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  e any resources 
12b70 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78  acquired.** by x
12b80 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44  Init.  The pAppD
12b90 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75  ata pointer is u
12ba0 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  sed as the only 
12bb0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
12bc0 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64  xInit and xShutd
12bd0 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  own..**.** SQLit
12be0 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  e holds the [SQL
12bf0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
12c00 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77  _MASTER] mutex w
12c10 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a  hen it invokes.*
12c20 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * the xInit meth
12c30 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74  od, so the xInit
12c40 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74   method need not
12c50 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
12c60 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77   The.** xShutdow
12c70 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79  n method is only
12c80 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71   called from [sq
12c90 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
12ca0 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20  ] so it does.** 
12cb0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74  not need to be t
12cc0 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72  hreadsafe either
12cd0 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72  .  For all other
12ce0 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65   methods, SQLite
12cf0 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  .** holds the [S
12d00 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
12d10 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73  IC_MEM] mutex as
12d20 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20   long as the.** 
12d30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12d40 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67  EMSTATUS] config
12d50 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
12d60 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69  s turned on (whi
12d70 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64  ch.** it is by d
12d80 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74  efault) and so t
12d90 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61  he methods are a
12da0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72  utomatically ser
12db0 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65  ialized..** Howe
12dc0 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f  ver, if [SQLITE_
12dd0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
12de0 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74  ] is disabled, t
12df0 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  hen the other.**
12e00 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65   methods must be
12e10 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65   threadsafe or e
12e20 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f  lse make their o
12e30 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20  wn arrangements 
12e40 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61  for.** serializa
12e50 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  tion..**.** SQLi
12e60 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e  te will never in
12e70 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72  voke xInit() mor
12e80 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68  e than once with
12e90 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69  out an interveni
12ea0 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53  ng.** call to xS
12eb0 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79  hutdown()..*/.ty
12ec0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
12ed0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
12ee0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
12ef0 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
12f00 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
12f10 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
12f20 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
12f30 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
12f40 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
12f50 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
12f60 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
12f70 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
12f80 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
12f90 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
12fa0 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
12fb0 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
12fc0 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
12fd0 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
12fe0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
12ff0 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
13000 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
13010 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
13020 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
13030 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
13040 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
13050 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
13060 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
13070 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
13080 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
13090 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
130a0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
130b0 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
130c0 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
130d0 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
130e0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
130f0 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
13100 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
13110 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
13120 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
13130 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
13140 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
13150 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
13160 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20  tion Options.** 
13170 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69  KEYWORDS: {confi
13180 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d  guration option}
13190 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
131a0 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
131b0 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
131c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
131d0 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
131e0 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
131f0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
13200 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
13210 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
13220 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
13230 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
13240 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
13250 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
13260 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
13270 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
13280 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13290 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
132a0 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
132b0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
132c0 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
132d0 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
132e0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
132f0 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
13300 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
13310 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71  worked.  The [sq
13320 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13330 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
13340 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
13350 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
13360 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
13370 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
13380 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
13390 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
133a0 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
133b0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
133c0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
133d0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
133e0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
133f0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
13400 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
13410 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
13420 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
13430 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
13440 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
13450 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  to Single-thread
13460 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
13470 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
13480 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61  * all mutexing a
13490 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69  nd puts SQLite i
134a0 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65  nto a mode where
134b0 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20   it can only be 
134c0 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e  used.** by a sin
134d0 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49  gle thread.   ^I
134e0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
134f0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
13500 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
13510 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
13520 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
13530 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
13540 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
13550 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61   possible to cha
13560 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  nge the [threadi
13570 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74  ng mode] from it
13580 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c  s default.** val
13590 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72  ue of Single-thr
135a0 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69  ead and so [sqli
135b0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
135c0 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53  ll return .** [S
135d0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
135e0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  called with the 
135f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
13600 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f  NGLETHREAD.** co
13610 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13620 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
13630 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
13640 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74  ULTITHREAD]] <dt
13650 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
13660 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a  ULTITHREAD</dt>.
13670 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
13680 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
13690 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
136a0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
136b0 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
136c0 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74  ng mode] to Mult
136d0 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  i-thread.  In ot
136e0 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
136f0 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69  sables.** mutexi
13700 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ng on [database 
13710 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
13720 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
13730 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
13740 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
13750 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
13760 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20  for serializing 
13770 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61  access to.** [da
13780 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13790 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
137a0 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20  d statements].  
137b0 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65  But other mutexe
137c0 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64  s.** are enabled
137d0 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20   so that SQLite 
137e0 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20  will be safe to 
137f0 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74  use in a multi-t
13800 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72  hreaded.** envir
13810 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61  onment as long a
13820 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73  s no two threads
13830 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
13840 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74  the same.** [dat
13850 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13860 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  ] at the same ti
13870 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20  me.  ^If SQLite 
13880 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13890 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
138a0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
138b0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
138c0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
138d0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
138e0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
138f0 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74   to set the Mult
13900 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
13910 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
13920 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
13930 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
13940 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
13950 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
13960 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
13970 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63  IG_MULTITHREAD c
13980 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13990 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
139a0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
139b0 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74  SERIALIZED]] <dt
139c0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
139d0 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a  ERIALIZED</dt>.*
139e0 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
139f0 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
13a00 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
13a10 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
13a20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
13a30 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61  g mode] to Seria
13a40 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20  lized. In other 
13a50 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69  words, this opti
13a60 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c  on enables.** al
13a70 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64  l mutexes includ
13a80 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76  ing the recursiv
13a90 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20  e.** mutexes on 
13aa0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
13ab0 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
13ac0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
13ad0 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68  bjects..** In th
13ae0 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69  is mode (which i
13af0 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68  s the default wh
13b00 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
13b10 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53  piled with.** [S
13b20 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13b30 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20  =1]) the SQLite 
13b40 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73  library will its
13b50 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63  elf serialize ac
13b60 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61  cess.** to [data
13b70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
13b80 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
13b90 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74  statements] so t
13ba0 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69  hat the.** appli
13bb0 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74  cation is free t
13bc0 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b  o use the same [
13bd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13be0 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73  ion] or the.** s
13bf0 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
13c00 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66  atement] in diff
13c10 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74  erent threads at
13c20 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a   the same time..
13c30 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  ** ^If SQLite is
13c40 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
13c50 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
13c60 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
13c70 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
13c80 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
13c90 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
13ca0 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
13cb0 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c  o set the Serial
13cc0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
13cd0 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
13ce0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13cf0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
13d00 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
13d10 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
13d20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
13d30 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67  ERIALIZED config
13d40 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
13d50 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13d60 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
13d70 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
13d80 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74  ONFIG_MALLOC</dt
13d90 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
13da0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
13db0 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65  LLOC option take
13dc0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
13dd0 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a  ent which is .**
13de0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
13df0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
13e00 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
13e10 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
13e20 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
13e30 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
13e40 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
13e50 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
13e60 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
13e70 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
13e80 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
13e90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13ea0 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
13eb0 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53  nto SQLite.)^ ^S
13ec0 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69  QLite makes.** i
13ed0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
13ee0 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
13ef0 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
13f00 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
13f10 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66  structure.** bef
13f20 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ore the [sqlite3
13f30 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20  _config()] call 
13f40 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  returns.</dd>.**
13f50 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13f60 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20  FIG_GETMALLOC]] 
13f70 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13f80 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
13f90 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
13fa0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13fb0 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61  MALLOC option ta
13fc0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
13fd0 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
13fe0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
13ff0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
14000 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
14010 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
14020 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  e..** The [sqlit
14030 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
14040 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
14050 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
14060 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
14070 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
14080 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  ion routines.)^.
14090 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
140a0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
140b0 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
140c0 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
140d0 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
140e0 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
140f0 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73  that simulations
14100 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14110 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a  on failure or.**
14120 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75   tracks memory u
14130 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c  sage, for exampl
14140 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
14150 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
14160 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  MALL_MALLOC]] <d
14170 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14180 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64 74  SMALL_MALLOC</dt
14190 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
141a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41  QLITE_CONFIG_SMA
141b0 4c 4c 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e  LL_MALLOC option
141c0 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
141d0 67 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74 79 70  gument of.** typ
141e0 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74  e int, interpret
141f0 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c  ed as a boolean,
14200 20 77 68 69 63 68 20 69 66 20 74 72 75 65 20 70   which if true p
14210 72 6f 76 69 64 65 73 20 61 20 68 69 6e 74 20 74  rovides a hint t
14220 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 74 68 61 74  o.** SQLite that
14230 20 69 74 20 73 68 6f 75 6c 64 20 61 76 6f 69 64   it should avoid
14240 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c   large memory al
14250 6c 6f 63 61 74 69 6f 6e 73 20 69 66 20 70 6f 73  locations if pos
14260 73 69 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65  sible..** SQLite
14270 20 77 69 6c 6c 20 72 75 6e 20 66 61 73 74 65 72   will run faster
14280 20 69 66 20 69 74 20 69 73 20 66 72 65 65 20 74   if it is free t
14290 6f 20 6d 61 6b 65 20 6c 61 72 67 65 20 6d 65 6d  o make large mem
142a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c  ory allocations,
142b0 0a 2a 2a 20 62 75 74 20 73 6f 6d 65 20 61 70 70  .** but some app
142c0 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 70  lication might p
142d0 72 65 66 65 72 20 74 6f 20 72 75 6e 20 73 6c 6f  refer to run slo
142e0 77 65 72 20 69 6e 20 65 78 63 68 61 6e 67 65 20  wer in exchange 
142f0 66 6f 72 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  for.** guarantee
14300 73 20 61 62 6f 75 74 20 6d 65 6d 6f 72 79 20 66  s about memory f
14310 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61  ragmentation tha
14320 74 20 61 72 65 20 70 6f 73 73 69 62 6c 65 20 69  t are possible i
14330 66 20 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f 63  f large.** alloc
14340 61 74 69 6f 6e 73 20 61 72 65 20 61 76 6f 69 64  ations are avoid
14350 65 64 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  ed.  This hint i
14360 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e 0a  s normally off..
14370 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
14380 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
14390 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53  EMSTATUS]] <dt>S
143a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
143b0 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  STATUS</dt>.** <
143c0 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
143d0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
143e0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
143f0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
14400 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e   type int,.** in
14410 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62  terpreted as a b
14420 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
14430 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
14440 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
14450 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c   of.** memory al
14460 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
14470 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f  ics. ^(When memo
14480 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
14490 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20  atistics are.** 
144a0 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f  disabled, the fo
144b0 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
144c0 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
144d0 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
144e0 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
144f0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
14500 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
14510 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
14520 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
14530 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
14540 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
14550 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20  p_limit64()].** 
14560 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
14570 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20  status64()].**  
14580 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d   </ul>)^.** ^Mem
14590 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
145a0 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e  tatistics are en
145b0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
145c0 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69   unless SQLite i
145d0 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
145e0 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55  th [SQLITE_DEFAU
145f0 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20  LT_MEMSTATUS]=0 
14600 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65  in which case me
14610 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
14620 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
14630 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
14640 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  fault..** </dd>.
14650 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14660 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20  ONFIG_SCRATCH]] 
14670 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14680 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a  G_SCRATCH</dt>.*
14690 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54  * <dd> The SQLIT
146a0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
146b0 20 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f   option is no lo
146c0 6e 67 65 72 20 75 73 65 64 2e 0a 2a 2a 20 3c 2f  nger used..** </
146d0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
146e0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
146f0 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CHE]] <dt>SQLITE
14700 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
14710 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
14720 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14730 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 69  G_PAGECACHE opti
14740 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 6d  on specifies a m
14750 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68  emory pool.** th
14760 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
14770 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  e for the databa
14780 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
14790 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
147a0 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
147b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a  lementation.  .*
147c0 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61  * This configura
147d0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61  tion option is a
147e0 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70   no-op if an app
147f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20  lication-define 
14800 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
14810 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
14820 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65  loaded using the
14830 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
14840 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68  PCACHE2]..** ^Th
14850 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
14860 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
14870 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
14880 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  HE: A pointer to
14890 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e  .** 8-byte align
148a0 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29  ed memory (pMem)
148b0 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
148c0 63 68 20 70 61 67 65 20 63 61 63 68 65 20 6c 69  ch page cache li
148d0 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  ne (sz),.** and 
148e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61  the number of ca
148f0 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a  che lines (N)..*
14900 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
14910 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
14920 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
14930 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
14940 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
14950 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
14960 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73   and 65536) plus
14970 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65   some extra byte
14980 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61  s for each.** pa
14990 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65  ge header.  ^The
149a0 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61   number of extra
149b0 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79   bytes needed by
149c0 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72   the page header
149d0 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72  .** can be deter
149e0 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c  mined using [SQL
149f0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
14a00 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74  E_HDRSZ]..** ^It
14a10 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
14a20 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
14a30 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66  ted memory,.** f
14a40 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65  or the sz parame
14a50 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72  ter to be larger
14a60 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e   than necessary.
14a70 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72    The pMem.** ar
14a80 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65  gument must be e
14a90 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
14aa0 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65  nter or a pointe
14ab0 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a  r to an 8-byte.*
14ac0 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20  * aligned block 
14ad0 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20  of memory of at 
14ae0 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
14af0 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73  , otherwise.** s
14b00 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
14b10 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
14b20 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69  .** ^When pMem i
14b30 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
14b40 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74  te will strive t
14b50 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  o use the memory
14b60 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20   provided.** to 
14b70 73 61 74 69 73 66 79 20 70 61 67 65 20 63 61 63  satisfy page cac
14b80 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e  he needs, fallin
14b90 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74  g back to [sqlit
14ba0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a  e3_malloc()] if.
14bb0 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 65 20  ** a page cache 
14bc0 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74  line is larger t
14bd0 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20  han sz bytes or 
14be0 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d  if all of the pM
14bf0 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  em buffer.** is 
14c00 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49  exhausted..** ^I
14c10 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61  f pMem is NULL a
14c20 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f  nd N is non-zero
14c30 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 74 61  , then each data
14c40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
14c50 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69  ** does an initi
14c60 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69  al bulk allocati
14c70 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63 68  on for page cach
14c80 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d  e memory.** from
14c90 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
14ca0 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66  ()] sufficient f
14cb0 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73  or N cache lines
14cc0 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76   if N is positiv
14cd0 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34  e or.** of -1024
14ce0 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69 73  *N bytes if N is
14cf0 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66   negative, . ^If
14d00 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
14d10 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
14d20 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
14d30 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
14d40 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 69 61  ed by the initia
14d50 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  l.** allocation,
14d60 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65   then SQLite goe
14d70 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  s to [sqlite3_ma
14d80 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65  lloc()] separate
14d90 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61  ly for each.** a
14da0 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20  dditional cache 
14db0 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  line. </dd>.**.*
14dc0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14dd0 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c  G_HEAP]] <dt>SQL
14de0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
14df0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
14e00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14e10 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63  HEAP option spec
14e20 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
14e30 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a  emory buffer .**
14e40 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
14e50 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  l use for all of
14e60 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
14e70 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
14e80 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74  eeds.** beyond t
14e90 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f  hose provided fo
14ea0 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
14eb0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
14ec0 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  ** ^The SQLITE_C
14ed0 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f  ONFIG_HEAP optio
14ee0 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
14ef0 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
14f00 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74   compiled.** wit
14f10 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  h either [SQLITE
14f20 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
14f30 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42   or [SQLITE_ENAB
14f40 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20  LE_MEMSYS5] and 
14f50 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
14f60 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76  TE_ERROR] if inv
14f70 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a  oked otherwise..
14f80 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68  ** ^There are th
14f90 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
14fa0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
14fb0 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74  EAP:.** An 8-byt
14fc0 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65  e aligned pointe
14fd0 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
14fe0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
14ff0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  f bytes in the m
15000 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
15010 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
15020 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a  location size..*
15030 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20  * ^If the first 
15040 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
15050 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
15060 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
15070 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
15080 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
15090 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
150a0 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
150b0 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
150c0 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
150d0 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
150e0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
150f0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
15100 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  C].  ^If the.** 
15110 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
15120 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
15130 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
15140 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
15150 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
15160 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
15170 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
15180 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
15190 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
151a0 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
151b0 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
151c0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
151d0 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
151e0 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
151f0 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
15200 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
15210 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  efined..** The m
15220 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
15230 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64  n size is capped
15240 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f   at 2**12. Reaso
15250 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20  nable values.** 
15260 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  for the minimum 
15270 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
15280 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68  are 2**5 through
15290 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   2**8.</dd>.**.*
152a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
152b0 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  G_MUTEX]] <dt>SQ
152c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
152d0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
152e0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
152f0 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20  IG_MUTEX option 
15300 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
15310 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
15320 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
15330 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
15340 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
15350 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
15360 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72  cture..** The ar
15370 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
15380 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
15390 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
153a0 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
153b0 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65  .** in place the
153c0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
153d0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
153e0 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  e.)^  ^SQLite ma
153f0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  kes a copy of.**
15400 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
15410 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
15420 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
15430 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65  cture before the
15440 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
15450 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72  ite3_config()] r
15460 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69  eturns. ^If SQLi
15470 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
15480 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
15490 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
154a0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
154b0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
154c0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
154d0 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
154e0 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
154f0 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
15500 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
15510 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
15520 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
15530 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
15540 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63  E_CONFIG_MUTEX c
15550 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15560 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
15570 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
15580 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
15590 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
155a0 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  TMUTEX]] <dt>SQL
155b0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
155c0 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
155d0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
155e0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70  NFIG_GETMUTEX op
155f0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
15600 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
15610 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
15620 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
15630 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
15640 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
15650 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
15660 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
15670 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
15680 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
15690 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
156a0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
156b0 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  tex routines.)^.
156c0 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
156d0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
156e0 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
156f0 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74  lt mutex allocat
15700 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
15710 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75  with a wrapper u
15720 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74  sed to track mut
15730 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72  ex usage for per
15740 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66  formance.** prof
15750 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67  iling or testing
15760 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20  , for example.  
15770 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
15780 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
15790 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
157a0 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
157b0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
157c0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
157d0 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
157e0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
157f0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
15800 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
15810 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
15820 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
15830 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
15840 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
15850 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69  G_GETMUTEX confi
15860 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
15870 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
15880 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
15890 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
158a0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
158b0 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  IDE]] <dt>SQLITE
158c0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
158d0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
158e0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
158f0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74  IG_LOOKASIDE opt
15900 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
15910 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
15920 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65  ermine.** the de
15930 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f  fault size of lo
15940 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f  okaside memory o
15950 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65  n each [database
15960 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
15970 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
15980 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
15990 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
159a0 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
159b0 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
159c0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
159d0 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
159e0 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
159f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
15a00 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e  )^  ^(SQLITE_CON
15a10 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a  FIG_LOOKASIDE.**
15a20 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66   sets the <i>def
15a30 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
15a40 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
15a50 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
15a60 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69  OKASIDE].** opti
15a70 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  on to [sqlite3_d
15a80 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
15a90 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
15aa0 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
15ab0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
15ac0 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
15ad0 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f  onnections.)^ </
15ae0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15af0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15b00 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
15b10 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64  ONFIG_PCACHE2</d
15b20 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
15b30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
15b40 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
15b50 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
15b60 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a  ument which is .
15b70 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
15b80 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
15b90 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
15ba0 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
15bb0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
15bc0 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
15bd0 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
15be0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
15bf0 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65  on.)^.** ^SQLite
15c00 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
15c10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63   the [sqlite3_pc
15c20 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
15c30 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  bject.</dd>.**.*
15c40 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15c50 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c  G_GETPCACHE2]] <
15c60 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15c70 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e  _GETPCACHE2</dt>
15c80 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
15c90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15ca0 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74  PCACHE2 option t
15cb0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
15cc0 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
15cd0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
15ce0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
15cf0 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
15d00 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
15d10 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75  ies of.** the cu
15d20 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65  rrent page cache
15d30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
15d40 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
15d50 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
15d60 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15d70 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOG]] <dt>SQLITE
15d80 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e  _CONFIG_LOG</dt>
15d90 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c  .** <dd> The SQL
15da0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
15db0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
15dc0 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53   configure the S
15dd0 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20  QLite.** global 
15de0 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20  [error log]..** 
15df0 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  (^The SQLITE_CON
15e00 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74  FIG_LOG option t
15e10 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
15e20 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ts: a pointer to
15e30 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77   a.** function w
15e40 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61  ith a call signa
15e50 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28  ture of void(*)(
15e60 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
15e70 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20  char*), .** and 
15e80 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69  a pointer to voi
15e90 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  d. ^If the funct
15ea0 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
15eb0 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a  ot NULL, it is.*
15ec0 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71  * invoked by [sq
15ed0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20  lite3_log()] to 
15ee0 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67  process each log
15ef0 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  ging event.  ^If
15f00 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
15f10 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c   pointer is NULL
15f20 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  , the [sqlite3_l
15f30 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  og()] interface 
15f40 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e  becomes a no-op.
15f50 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f  .** ^The void po
15f60 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68  inter that is th
15f70 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
15f80 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  t to SQLITE_CONF
15f90 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73  IG_LOG is.** pas
15fa0 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
15fb0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
15fc0 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  er to the applic
15fd0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
15fe0 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
15ff0 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66   whenever that f
16000 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
16010 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ed.  ^The second
16020 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
16030 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
16040 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f  tion is a copy o
16050 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
16060 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72  meter to the cor
16070 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73  responding.** [s
16080 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61  qlite3_log()] ca
16090 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64  ll and is intend
160a0 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75  ed to be a [resu
160b0 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  lt code] or an.*
160c0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
160d0 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20  lt code].  ^The 
160e0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
160f0 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f  passed to the lo
16100 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d  gger is.** log m
16110 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72  essage after for
16120 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c  matting via [sql
16130 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
16140 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
16150 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63  logging interfac
16160 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  e is not reentra
16170 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66  nt; the logger f
16180 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  unction.** suppl
16190 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  ied by the appli
161a0 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
161b0 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74  invoke any SQLit
161c0 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
161d0 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  In a multi-threa
161e0 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ded application,
161f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
16200 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
16210 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
16220 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
16230 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
16240 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
16250 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
16260 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e  FIG_URI.** <dd>^
16270 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
16280 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61  IG_URI option ta
16290 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
162a0 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
162b0 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72  t..** If non-zer
162c0 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64  o, then URI hand
162d0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
162e0 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65   enabled. If the
162f0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65   parameter is ze
16300 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20  ro,.** then URI 
16310 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
16320 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e  ally disabled.)^
16330 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e   ^If URI handlin
16340 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
16350 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69   enabled, all fi
16360 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74  lenames passed t
16370 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
16380 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
16390 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  n_v2()],.** [sql
163a0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f  ite3_open16()] o
163b0 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61  r.** specified a
163c0 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43  s part of [ATTAC
163d0 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20  H] commands are 
163e0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
163f0 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a  RIs, regardless.
16400 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ** of whether or
16410 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45   not the [SQLITE
16420 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
16430 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  is set when the 
16440 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
16450 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
16460 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62  . ^If it is glob
16470 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66  ally disabled, f
16480 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  ilenames are.** 
16490 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64  only interpreted
164a0 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20   as URIs if the 
164b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
164c0 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
164d0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
164e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
164f0 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61  pened. ^(By defa
16500 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e  ult, URI handlin
16510 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
16520 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64   disabled. The d
16530 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79  efault value may
16540 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63   be changed by c
16550 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68  ompiling with th
16560 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45  e.** [SQLITE_USE
16570 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66  _URI] symbol def
16580 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ined.)^.**.** [[
16590 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
165a0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
165b0 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  N]] <dt>SQLITE_C
165c0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
165d0 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64  NDEX_SCAN.** <dd
165e0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
165f0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
16600 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74  EX_SCAN option t
16610 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e  akes a single in
16620 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  teger.** argumen
16630 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72  t which is inter
16640 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
16650 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ean in order to 
16660 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
16670 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  e.** the use of 
16680 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
16690 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
166a0 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65  scans in the que
166b0 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a  ry optimizer..**
166c0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
166d0 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69  tting is determi
166e0 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53  ned.** by the [S
166f0 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45  QLITE_ALLOW_COVE
16700 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
16710 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
16720 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22  tion, or is "on"
16730 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70  .** if that comp
16740 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
16750 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54  is omitted..** T
16760 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69  he ability to di
16770 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66  sable the use of
16780 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
16790 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
167a0 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63   scans.** is bec
167b0 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72  ause some incorr
167c0 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61  ectly coded lega
167d0 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  cy applications 
167e0 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f  might malfunctio
167f0 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70  n.** when the op
16800 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e  timization is en
16810 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e  abled.  Providin
16820 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f  g the ability to
16830 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20  .** disable the 
16840 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c  optimization all
16850 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62  ows the older, b
16860 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  uggy application
16870 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   code to work.**
16880 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20   without change 
16890 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20  even with newer 
168a0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
168b0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  te..**.** [[SQLI
168c0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
168d0 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ]] [[SQLITE_CONF
168e0 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a  IG_GETPCACHE]].*
168f0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
16900 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53  FIG_PCACHE and S
16910 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16920 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54  PCACHE.** <dd> T
16930 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65  hese options are
16940 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68   obsolete and sh
16950 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
16960 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a   by new code..**
16970 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e   They are retain
16980 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
16990 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62   compatibility b
169a0 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70  ut are now no-op
169b0 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
169c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
169d0 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64  G_SQLLOG]].** <d
169e0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
169f0 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68  SQLLOG.** <dd>Th
16a00 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  is option is onl
16a10 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73  y available if s
16a20 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  qlite is compile
16a30 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
16a40 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c  QLITE_ENABLE_SQL
16a50 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73  LOG] pre-process
16a60 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64  or macro defined
16a70 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  . The first argu
16a80 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62  ment should.** b
16a90 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
16aa0 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
16ab0 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  e void(*)(void*,
16ac0 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63  sqlite3*,const c
16ad0 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54  har*, int)..** T
16ae0 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64  he second should
16af0 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69   be of type (voi
16b00 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63  d*). The callbac
16b10 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  k is invoked by 
16b20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69  the library.** i
16b30 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65  n three separate
16b40 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
16b50 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
16b60 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
16b70 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  s the.** fourth 
16b80 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68  parameter. If th
16b90 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
16ba0 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68  er is 0, then th
16bb0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
16bc0 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20  ction.** passed 
16bd0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
16be0 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20  gument has just 
16bf0 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65  been opened. The
16c00 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
16c10 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62  ** points to a b
16c20 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67  uffer containing
16c30 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
16c40 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
16c50 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66  ile. If the.** f
16c60 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
16c70 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53  is 1, then the S
16c80 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
16c90 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  t the third para
16ca0 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20  meter.** points 
16cb0 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  to has just been
16cc0 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69   executed. Or, i
16cd0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
16ce0 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65  ameter is 2, the
16cf0 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74  n.** the connect
16d00 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64  ion being passed
16d10 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
16d20 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e  arameter is bein
16d30 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a  g closed. The.**
16d40 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
16d50 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20   is passed NULL 
16d60 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41  In this case.  A
16d70 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69  n example of usi
16d80 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69  ng this.** confi
16d90 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
16da0 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74  can be seen in t
16db0 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e  he "test_sqllog.
16dc0 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69  c" source file i
16dd0 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63  n.** the canonic
16de0 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  al SQLite source
16df0 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   tree.</dd>.**.*
16e00 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
16e10 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  G_MMAP_SIZE]].**
16e20 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16e30 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20  IG_MMAP_SIZE.** 
16e40 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46  <dd>^SQLITE_CONF
16e50 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b  IG_MMAP_SIZE tak
16e60 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e  es two 64-bit in
16e70 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69  teger (sqlite3_i
16e80 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20  nt64) values.** 
16e90 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66  that are the def
16ea0 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c  ault mmap size l
16eb0 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c  imit (the defaul
16ec0 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a  t setting for.**
16ed0 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
16ee0 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78  ze]) and the max
16ef0 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61  imum allowed mma
16f00 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a  p size limit..**
16f10 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
16f20 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65  tting can be ove
16f30 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20  rridden by each 
16f40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16f50 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74  ion using.** eit
16f60 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20  her the [PRAGMA 
16f70 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61  mmap_size] comma
16f80 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20  nd, or by using 
16f90 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
16fa0 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
16fb0 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e  file control.  ^
16fc0 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c  (The maximum all
16fd0 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a  owed mmap size.*
16fe0 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74  * will be silent
16ff0 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20  ly truncated if 
17000 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61  necessary so tha
17010 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78  t it does not ex
17020 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ceed the.** comp
17030 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d  ile-time maximum
17040 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62   mmap size set b
17050 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
17060 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  _MAX_MMAP_SIZE] 
17070 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
17080 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69  ion.)^.** ^If ei
17090 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f  ther argument to
170a0 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
170b0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
170c0 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  hat argument is.
170d0 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74  ** changed to it
170e0 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64  s compile-time d
170f0 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  efault..**.** [[
17100 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
17110 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a  N32_HEAPSIZE]].*
17120 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
17130 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
17140 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  ZE.** <dd>^The S
17150 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
17160 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69  32_HEAPSIZE opti
17170 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
17180 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
17190 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f  s.** compiled fo
171a0 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74  r Windows with t
171b0 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32  he [SQLITE_WIN32
171c0 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f  _MALLOC] pre-pro
171d0 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20  cessor macro.** 
171e0 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45  defined. ^SQLITE
171f0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
17200 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33  APSIZE takes a 3
17210 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  2-bit unsigned i
17220 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20  nteger value.** 
17230 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
17240 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
17250 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68  of the created h
17260 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  eap..**.** [[SQL
17270 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
17280 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74  E_HDRSZ]].** <dt
17290 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
172a0 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c  CACHE_HDRSZ.** <
172b0 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
172c0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
172d0 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  SZ option takes 
172e0 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
172f0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  er which.** is a
17300 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
17310 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65  nteger and write
17320 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65  s into that inte
17330 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ger the number o
17340 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73  f extra.** bytes
17350 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72   per page requir
17360 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65  ed for each page
17370 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   in [SQLITE_CONF
17380 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
17390 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  * The amount of 
173a0 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75  extra space requ
173b0 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20  ired can change 
173c0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
173d0 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61   compiler,.** ta
173e0 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61  rget platform, a
173f0 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
17400 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  n..**.** [[SQLIT
17410 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d  E_CONFIG_PMASZ]]
17420 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
17430 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c  ONFIG_PMASZ.** <
17440 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
17450 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69  ONFIG_PMASZ opti
17460 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
17470 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
17480 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67  h.** is an unsig
17490 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
174a0 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75  sets the "Minimu
174b0 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20  m PMA Size" for 
174c0 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65  the multithreade
174d0 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74  d.** sorter to t
174e0 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68  hat integer.  Th
174f0 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75  e default minimu
17500 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65  m PMA Size is se
17510 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  t by the.** [SQL
17520 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a  ITE_SORTER_PMASZ
17530 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
17540 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65  ption.  New thre
17550 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64  ads are launched
17560 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68  .** to help with
17570 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73   sort operations
17580 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61   when multithrea
17590 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69  ded sorting.** i
175a0 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67  s enabled (using
175b0 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72   the [PRAGMA thr
175c0 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61  eads] command) a
175d0 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  nd the amount of
175e0 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62   content.** to b
175f0 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73  e sorted exceeds
17600 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74   the page size t
17610 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d  imes the minimum
17620 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47   of the.** [PRAG
17630 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73  MA cache_size] s
17640 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20  etting and this 
17650 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  value..**.** [[S
17660 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
17670 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a  TJRNL_SPILL]].**
17680 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
17690 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
176a0 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  L.** <dd>^The SQ
176b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
176c0 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f  JRNL_SPILL optio
176d0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
176e0 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
176f0 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20  .** becomes the 
17700 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e  [statement journ
17710 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73  al] spill-to-dis
17720 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a  k threshold.  .*
17730 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75  * [Statement jou
17740 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20  rnals] are held 
17750 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20  in memory until 
17760 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62  their size (in b
17770 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73  ytes).** exceeds
17780 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c   this threshold,
17790 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20   at which point 
177a0 74 68 65 79 20 61 72 65 20 77 72 69 74 74 65 6e  they are written
177b0 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20   to disk..** Or 
177c0 69 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64  if the threshold
177d0 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e   is -1, statemen
177e0 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61  t journals are a
177f0 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78  lways held.** ex
17800 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d  clusively in mem
17810 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61  ory..** Since ma
17820 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75  ny statement jou
17830 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f  rnals never beco
17840 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e  me large, settin
17850 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74  g the spill.** t
17860 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61  hreshold to a va
17870 6c 75 65 20 73 75 63 68 20 61 73 20 36 34 4b 69  lue such as 64Ki
17880 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65  B can greatly re
17890 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20  duce the amount 
178a0 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72  of.** I/O requir
178b0 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74  ed to support st
178c0 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b  atement rollback
178d0 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  ..** The default
178e0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20   value for this 
178f0 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72  setting is contr
17900 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  olled by the.** 
17910 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c  [SQLITE_STMTJRNL
17920 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d  _SPILL] compile-
17930 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a  time option..**.
17940 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
17950 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a  IG_SORTERREF_SIZ
17960 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
17970 45 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52  E_CONFIG_SORTERR
17980 45 46 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 54  EF_SIZE.** <dd>T
17990 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
179a0 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 20  _SORTERREF_SIZE 
179b0 6f 70 74 69 6f 6e 20 61 63 63 65 70 74 73 20 61  option accepts a
179c0 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
179d0 72 0a 2a 2a 20 6f 66 20 74 79 70 65 20 28 69 6e  r.** of type (in
179e0 74 29 20 2d 20 74 68 65 20 6e 65 77 20 76 61 6c  t) - the new val
179f0 75 65 20 6f 66 20 74 68 65 20 73 6f 72 74 65 72  ue of the sorter
17a00 2d 72 65 66 65 72 65 6e 63 65 20 73 69 7a 65 20  -reference size 
17a10 74 68 72 65 73 68 6f 6c 64 2e 0a 2a 2a 20 55 73  threshold..** Us
17a20 75 61 6c 6c 79 2c 20 77 68 65 6e 20 53 51 4c 69  ually, when SQLi
17a30 74 65 20 75 73 65 73 20 61 6e 20 65 78 74 65 72  te uses an exter
17a40 6e 61 6c 20 73 6f 72 74 20 74 6f 20 6f 72 64 65  nal sort to orde
17a50 72 20 72 65 63 6f 72 64 73 20 61 63 63 6f 72 64  r records accord
17a60 69 6e 67 0a 2a 2a 20 74 6f 20 61 6e 20 4f 52 44  ing.** to an ORD
17a70 45 52 20 42 59 20 63 6c 61 75 73 65 2c 20 61 6c  ER BY clause, al
17a80 6c 20 66 69 65 6c 64 73 20 72 65 71 75 69 72 65  l fields require
17a90 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 20  d by the caller 
17aa0 61 72 65 20 70 72 65 73 65 6e 74 20 69 6e 20 74  are present in t
17ab0 68 65 0a 2a 2a 20 73 6f 72 74 65 64 20 72 65 63  he.** sorted rec
17ac0 6f 72 64 73 2e 20 48 6f 77 65 76 65 72 2c 20 69  ords. However, i
17ad0 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69  f SQLite determi
17ae0 6e 65 73 20 62 61 73 65 64 20 6f 6e 20 74 68 65  nes based on the
17af0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 0a 2a   declared type.*
17b00 2a 20 6f 66 20 61 20 74 61 62 6c 65 20 63 6f 6c  * of a table col
17b10 75 6d 6e 20 74 68 61 74 20 69 74 73 20 76 61 6c  umn that its val
17b20 75 65 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74  ues are likely t
17b30 6f 20 62 65 20 76 65 72 79 20 6c 61 72 67 65 20  o be very large 
17b40 2d 20 6c 61 72 67 65 72 0a 2a 2a 20 74 68 61 6e  - larger.** than
17b50 20 74 68 65 20 63 6f 6e 66 69 67 75 72 65 64 20   the configured 
17b60 73 6f 72 74 65 72 2d 72 65 66 65 72 65 6e 63 65  sorter-reference
17b70 20 73 69 7a 65 20 74 68 72 65 73 68 6f 6c 64 20   size threshold 
17b80 2d 20 74 68 65 6e 20 61 20 72 65 66 65 72 65 6e  - then a referen
17b90 63 65 0a 2a 2a 20 69 73 20 73 74 6f 72 65 64 20  ce.** is stored 
17ba0 69 6e 20 65 61 63 68 20 73 6f 72 74 65 64 20 72  in each sorted r
17bb0 65 63 6f 72 64 20 61 6e 64 20 74 68 65 20 72 65  ecord and the re
17bc0 71 75 69 72 65 64 20 63 6f 6c 75 6d 6e 20 76 61  quired column va
17bd0 6c 75 65 73 20 6c 6f 61 64 65 64 0a 2a 2a 20 66  lues loaded.** f
17be0 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73 65  rom the database
17bf0 20 61 73 20 72 65 63 6f 72 64 73 20 61 72 65 20   as records are 
17c00 72 65 74 75 72 6e 65 64 20 69 6e 20 73 6f 72 74  returned in sort
17c10 65 64 20 6f 72 64 65 72 2e 20 54 68 65 20 64 65  ed order. The de
17c20 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 66  fault.** value f
17c30 6f 72 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  or this option i
17c40 73 20 74 6f 20 6e 65 76 65 72 20 75 73 65 20 74  s to never use t
17c50 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  his optimization
17c60 2e 20 53 70 65 63 69 66 79 69 6e 67 20 61 20 0a  . Specifying a .
17c70 2a 2a 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75  ** negative valu
17c80 65 20 66 6f 72 20 74 68 69 73 20 6f 70 74 69 6f  e for this optio
17c90 6e 20 72 65 73 74 6f 72 65 73 20 74 68 65 20 64  n restores the d
17ca0 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 75 72  efault behaviour
17cb0 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ..** This option
17cc0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
17cd0 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  le if SQLite is 
17ce0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
17cf0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
17d00 42 4c 45 5f 53 4f 52 54 45 52 5f 52 45 46 45 52  BLE_SORTER_REFER
17d10 45 4e 43 45 53 5d 20 63 6f 6d 70 69 6c 65 2d 74  ENCES] compile-t
17d20 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c  ime option..** <
17d30 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
17d40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
17d50 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
17d60 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
17d70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
17d80 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
17d90 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
17da0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17db0 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
17dc0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
17dd0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17de0 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
17df0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
17e00 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
17e10 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17e20 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
17e30 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
17e40 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
17e50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17e60 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
17e70 20 20 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67     6  /* No long
17e80 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69  er used */.#defi
17e90 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17ea0 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
17eb0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
17ec0 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
17ed0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17ee0 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
17ef0 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
17f00 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
17f10 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17f20 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
17f30 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
17f40 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
17f50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
17f60 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
17f70 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
17f80 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
17f90 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17fa0 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
17fb0 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
17fc0 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
17fd0 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
17fe0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
17ff0 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
18000 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
18010 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
18020 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
18030 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
18040 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
18050 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
18060 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
18070 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
18080 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18090 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
180a0 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
180b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
180c0 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
180d0 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
180e0 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
180f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
18100 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
18110 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
18120 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18130 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
18140 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
18150 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
18160 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18170 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
18180 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
18190 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
181a0 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
181b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
181c0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
181d0 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  20  /* int */.#d
181e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
181f0 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20  FIG_SQLLOG      
18200 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c   21  /* xSqllog,
18210 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
18220 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18230 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20  MMAP_SIZE    22 
18240 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36   /* sqlite3_int6
18250 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  4, sqlite3_int64
18260 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18270 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
18280 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33  HEAPSIZE      23
18290 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
182a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
182b0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
182c0 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20  DRSZ        24  
182d0 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23  /* int *psz */.#
182e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
182f0 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20  NFIG_PMASZ      
18300 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20           25  /* 
18310 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50  unsigned int szP
18320 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ma */.#define SQ
18330 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
18340 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20  JRNL_SPILL      
18350 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65  26  /* int nByte
18360 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18370 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f  TE_CONFIG_SMALL_
18380 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 32 37  MALLOC        27
18390 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
183a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
183b0 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f  ONFIG_SORTERREF_
183c0 53 49 5a 45 20 20 20 20 20 20 32 38 20 20 2f 2a  SIZE      28  /*
183d0 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f   int nByte */../
183e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
183f0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
18400 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  on Configuration
18410 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54   Options.**.** T
18420 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
18430 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
18440 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
18450 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
18460 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
18470 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
18480 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
18490 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
184a0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
184b0 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
184c0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
184d0 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
184e0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
184f0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
18500 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
18510 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
18520 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
18530 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
18540 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
18550 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
18560 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
18570 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
18580 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
18590 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
185a0 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71  orked.  ^The [sq
185b0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
185c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
185d0 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
185e0 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
185f0 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
18600 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
18610 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
18620 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
18630 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
18640 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
18650 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
18660 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
18670 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
18680 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74  akes three addit
18690 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20  ional arguments 
186a0 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
186b0 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64  he .** [lookasid
186c0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
186d0 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  or] configuratio
186e0 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62  n for the [datab
186f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
18700 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
18710 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69  rgument (the thi
18720 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
18730 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
18740 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f  ig()] is a.** po
18750 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
18760 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20  y buffer to use 
18770 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  for lookaside me
18780 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  mory..** ^The fi
18790 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74  rst argument aft
187a0 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42  er the SQLITE_DB
187b0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
187c0 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20   verb.** may be 
187d0 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61  NULL in which ca
187e0 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  se SQLite will a
187f0 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c  llocate the.** l
18800 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
18810 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71  itself using [sq
18820 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
18830 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
18840 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
18850 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
18860 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
18870 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  ot.  ^The third 
18880 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
18890 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
188a0 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  ts.  The size of
188b0 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74   the buffer in t
188c0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
188d0 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65  t must be greate
188e0 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75  r than.** or equ
188f0 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63  al to the produc
18900 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t of the second 
18910 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65  and third argume
18920 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72  nts.  The buffer
18930 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67  .** must be alig
18940 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
18950 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20   boundary.  ^If 
18960 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
18970 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45  ent to.** SQLITE
18980 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
18990 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c  IDE is not a mul
189a0 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69  tiple of 8, it i
189b0 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  s internally.** 
189c0 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20  rounded down to 
189d0 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72  the next smaller
189e0 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20   multiple of 8. 
189f0 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65   ^(The lookaside
18a00 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69   memory.** confi
18a10 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64  guration for a d
18a20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18a30 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63  on can only be c
18a40 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74  hanged when that
18a50 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
18a60 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
18a70 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20  using lookaside 
18a80 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74  memory, or in ot
18a90 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65  her words.** whe
18aa0 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76  n the "current v
18ab0 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62  alue" returned b
18ac0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62  y.** [sqlite3_db
18ad0 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49  _status](D,[SQLI
18ae0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
18af0 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72  IDE],...) is zer
18b00 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  o..** Any attemp
18b10 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  t to change the 
18b20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
18b30 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77   configuration w
18b40 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  hen lookaside.**
18b50 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73   memory is in us
18b60 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e  e leaves the con
18b70 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61  figuration uncha
18b80 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73  nged and returns
18b90 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53   .** [SQLITE_BUS
18ba0 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Y].)^</dd>.**.**
18bb0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
18bc0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
18bd0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
18be0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
18bf0 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
18c00 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f  disable the enfo
18c10 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66  rcement of.** [f
18c20 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74  oreign key const
18c30 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20  raints].  There 
18c40 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
18c50 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
18c60 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
18c70 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
18c80 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
18c90 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b   0 to disable FK
18ca0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a   enforcement,.**
18cb0 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
18cc0 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
18cd0 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  nt or negative t
18ce0 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72  o leave FK enfor
18cf0 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e  cement.** unchan
18d00 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ged.  The second
18d10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
18d20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
18d30 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
18d40 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
18d50 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
18d60 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66  e whether FK enf
18d70 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20  orcement is off 
18d80 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  or on.** followi
18d90 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
18da0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18db0 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
18dc0 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
18dd0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
18de0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73  FK enforcement s
18df0 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
18e00 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
18e10 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18e20 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
18e30 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e  BLE_TRIGGER</dt>
18e40 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
18e50 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
18e60 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
18e70 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  le [CREATE TRIGG
18e80 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a  ER | triggers]..
18e90 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
18ea0 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
18eb0 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
18ec0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
18ed0 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
18ee0 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
18ef0 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c  isable triggers,
18f00 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
18f10 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20  enable triggers 
18f20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
18f30 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
18f40 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54   unchanged..** T
18f50 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18f60 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
18f70 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
18f80 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
18f90 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
18fa0 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
18fb0 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20  er triggers are 
18fc0 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
18fd0 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  led.** following
18fe0 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
18ff0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
19000 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
19010 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
19020 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72  hich case the tr
19030 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73  igger setting is
19040 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
19050 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
19060 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
19070 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f  FIG_ENABLE_FTS3_
19080 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a  TOKENIZER</dt>.*
19090 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
190a0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
190b0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
190c0 20 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e   the two-argumen
190d0 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  t.** version of 
190e0 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69  the [fts3_tokeni
190f0 7a 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  zer()] function 
19100 77 68 69 63 68 20 69 73 20 70 61 72 74 20 6f 66  which is part of
19110 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66   the.** [FTS3] f
19120 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20  ull-text search 
19130 65 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e  engine extension
19140 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
19150 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
19160 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
19170 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
19180 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
19190 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
191a0 20 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f   disable fts3_to
191b0 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20  kenizer() or.** 
191c0 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
191d0 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65  le fts3_tokenize
191e0 72 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20  r() or negative 
191f0 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
19200 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65  ting.** unchange
19210 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
19220 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
19230 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
19240 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
19250 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
19260 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
19270 65 20 77 68 65 74 68 65 72 20 66 74 73 33 5f 74  e whether fts3_t
19280 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61  okenizer is disa
19290 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a  bled or enabled.
192a0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
192b0 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
192c0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
192d0 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
192e0 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
192f0 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 65   case the new se
19300 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
19310 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
19320 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
19330 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
19340 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f  LE_LOAD_EXTENSIO
19350 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  N</dt>.** <dd> ^
19360 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
19370 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
19380 20 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73 71   disable the [sq
19390 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
193a0 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  sion()].** inter
193b0 66 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e 74  face independent
193c0 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f  ly of the [load_
193d0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c  extension()] SQL
193e0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
193f0 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  e [sqlite3_enabl
19400 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  e_load_extension
19410 28 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 20  ()] API enables 
19420 6f 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74 68  or disables both
19430 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73   the.** C-API [s
19440 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
19450 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65  nsion()] and the
19460 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c   SQL function [l
19470 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
19480 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
19490 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
194a0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
194b0 2a 20 57 68 65 6e 20 74 68 65 20 66 69 72 73 74  * When the first
194c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
194d0 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 31  s interface is 1
194e0 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20  , then only the 
194f0 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62  C-API is.** enab
19500 6c 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  led and the SQL 
19510 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73  function remains
19520 20 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74   disabled.  If t
19530 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
19540 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74  t to.** this int
19550 65 72 66 61 63 65 20 69 73 20 30 2c 20 74 68 65  erface is 0, the
19560 6e 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50 49  n both the C-API
19570 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e   and the SQL fun
19580 63 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62 6c  ction are disabl
19590 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  ed..** If the fi
195a0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
195b0 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e  -1, then no chan
195c0 67 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20  ges are made to 
195d0 73 74 61 74 65 20 6f 66 20 65 69 74 68 65 72 20  state of either 
195e0 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20  the.** C-API or 
195f0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
19600 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
19610 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
19620 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
19630 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
19640 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
19650 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
19660 20 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74 65   whether [sqlite
19670 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
19680 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
19690 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20   is disabled or 
196a0 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e  enabled followin
196b0 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
196c0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
196d0 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e  er may.** be a N
196e0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20  ULL pointer, in 
196f0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e  which case the n
19700 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  ew setting is no
19710 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
19720 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
19730 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
19740 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f  FIG_MAINDBNAME</
19750 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
19760 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
19770 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6e   to change the n
19780 61 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69 6e  ame of the "main
19790 22 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73 63  " database.** sc
197a0 68 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65  hema.  ^The sole
197b0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
197c0 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e 73  ointer to a cons
197d0 74 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e 67  tant UTF8 string
197e0 0a 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62  .** which will b
197f0 65 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73 63  ecome the new sc
19800 68 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61  hema name in pla
19810 63 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e  ce of "main".  ^
19820 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e  SQLite.** does n
19830 6f 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f  ot make a copy o
19840 66 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20 73  f the new main s
19850 63 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e  chema name strin
19860 67 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69 63  g, so the applic
19870 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e  ation.** must en
19880 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61 72  sure that the ar
19890 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 6e  gument passed in
198a0 74 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49 47  to this DBCONFIG
198b0 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68 61   option is uncha
198c0 6e 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66  nged.** until af
198d0 74 65 72 20 74 68 65 20 64 61 74 61 62 61 73 65  ter the database
198e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
198f0 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  es..** </dd>.**.
19900 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
19910 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f  CONFIG_NO_CKPT_O
19920 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20  N_CLOSE</dt>.** 
19930 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68  <dd> Usually, wh
19940 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 69 6e  en a database in
19950 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f   wal mode is clo
19960 73 65 64 20 6f 72 20 64 65 74 61 63 68 65 64 20  sed or detached 
19970 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62  from a .** datab
19980 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69  ase handle, SQLi
19990 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 68 69  te checks if thi
199a0 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74  s will mean that
199b0 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20 6e   there are now n
199c0 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  o .** connection
199d0 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 20  s at all to the 
199e0 64 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f 2c  database. If so,
199f0 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20 63   it performs a c
19a00 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70  heckpoint .** op
19a10 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 63  eration before c
19a20 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65  losing the conne
19a30 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69  ction. This opti
19a40 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20 74  on may be used t
19a50 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 68  o.** override th
19a60 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54 68  is behaviour. Th
19a70 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
19a80 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73  r passed to this
19a90 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73   operation.** is
19aa0 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 70 6f   an integer - po
19ab0 73 69 74 69 76 65 20 74 6f 20 64 69 73 61 62 6c  sitive to disabl
19ac0 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e  e checkpoints-on
19ad0 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20  -close, or zero 
19ae0 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29  (the.** default)
19af0 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d 2c   to enable them,
19b00 20 61 6e 64 20 6e 65 67 61 74 69 76 65 20 74 6f   and negative to
19b10 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
19b20 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  ng unchanged..**
19b30 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
19b40 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
19b50 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
19b60 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 69  .** into which i
19b70 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
19b80 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
19b90 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 73  ther checkpoints
19ba0 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76  -on-close.** hav
19bb0 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20  e been disabled 
19bc0 2d 20 30 20 69 66 20 74 68 65 79 20 61 72 65 20  - 0 if they are 
19bd0 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20  not disabled, 1 
19be0 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20  if they are..** 
19bf0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
19c00 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19c10 45 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74 3e  ENABLE_QPSG</dt>
19c20 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51  .** <dd>^(The SQ
19c30 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
19c40 41 42 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f 6e  ABLE_QPSG option
19c50 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64 65   activates or de
19c60 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68 65  activates.** the
19c70 20 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20   [query planner 
19c80 73 74 61 62 69 6c 69 74 79 20 67 75 61 72 61 6e  stability guaran
19c90 74 65 65 5d 20 28 51 50 53 47 29 2e 20 20 57 68  tee] (QPSG).  Wh
19ca0 65 6e 20 74 68 65 20 51 50 53 47 20 69 73 20 61  en the QPSG is a
19cb0 63 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e 67  ctive,.** a sing
19cc0 6c 65 20 53 51 4c 20 71 75 65 72 79 20 73 74 61  le SQL query sta
19cd0 74 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77 61  tement will alwa
19ce0 79 73 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  ys use the same 
19cf0 61 6c 67 6f 72 69 74 68 6d 20 72 65 67 61 72 64  algorithm regard
19d00 6c 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75 65  less.** of value
19d10 73 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61  s of [bound para
19d20 6d 65 74 65 72 73 5d 2e 29 5e 20 54 68 65 20 51  meters].)^ The Q
19d30 50 53 47 20 64 69 73 61 62 6c 65 73 20 73 6f 6d  PSG disables som
19d40 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 61  e query optimiza
19d50 74 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c 6f  tions.** that lo
19d60 6f 6b 20 61 74 20 74 68 65 20 76 61 6c 75 65 73  ok at the values
19d70 20 6f 66 20 62 6f 75 6e 64 20 70 61 72 61 6d 65   of bound parame
19d80 74 65 72 73 2c 20 77 68 69 63 68 20 63 61 6e 20  ters, which can 
19d90 6d 61 6b 65 20 73 6f 6d 65 20 71 75 65 72 69 65  make some querie
19da0 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42 75  s.** slower.  Bu
19db0 74 20 74 68 65 20 51 50 53 47 20 68 61 73 20 74  t the QPSG has t
19dc0 68 65 20 61 64 76 61 6e 74 61 67 65 20 6f 66 20  he advantage of 
19dd0 6d 6f 72 65 20 70 72 65 64 69 63 74 61 62 6c 65  more predictable
19de0 20 62 65 68 61 76 69 6f 72 2e 20 20 57 69 74 68   behavior.  With
19df0 0a 2a 2a 20 74 68 65 20 51 50 53 47 20 61 63 74  .** the QPSG act
19e00 69 76 65 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ive, SQLite will
19e10 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 65 20   always use the 
19e20 73 61 6d 65 20 71 75 65 72 79 20 70 6c 61 6e 20  same query plan 
19e30 69 6e 20 74 68 65 20 66 69 65 6c 64 20 61 73 0a  in the field as.
19e40 2a 2a 20 77 61 73 20 75 73 65 64 20 64 75 72 69  ** was used duri
19e50 6e 67 20 74 65 73 74 69 6e 67 20 69 6e 20 74 68  ng testing in th
19e60 65 20 6c 61 62 2e 0a 2a 2a 20 54 68 65 20 66 69  e lab..** The fi
19e70 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
19e80 74 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 20  this setting is 
19e90 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
19ea0 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
19eb0 20 0a 2a 2a 20 74 68 65 20 51 50 53 47 2c 20 70   .** the QPSG, p
19ec0 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
19ed0 65 20 51 50 53 47 2c 20 6f 72 20 6e 65 67 61 74  e QPSG, or negat
19ee0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
19ef0 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68   setting.** unch
19f00 61 6e 67 65 64 2e 20 54 68 65 20 73 65 63 6f 6e  anged. The secon
19f10 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
19f20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
19f30 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
19f40 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
19f50 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
19f60 74 65 20 77 68 65 74 68 65 72 20 74 68 65 20 51  te whether the Q
19f70 50 53 47 20 69 73 20 64 69 73 61 62 6c 65 64 20  PSG is disabled 
19f80 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
19f90 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
19fa0 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  l..** </dd>.**.*
19fb0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
19fc0 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51  ONFIG_TRIGGER_EQ
19fd0 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 42  P</dt>.** <dd> B
19fe0 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 6f  y default, the o
19ff0 75 74 70 75 74 20 6f 66 20 45 58 50 4c 41 49 4e  utput of EXPLAIN
1a000 20 51 55 45 52 59 20 50 4c 41 4e 20 63 6f 6d 6d   QUERY PLAN comm
1a010 61 6e 64 73 20 64 6f 65 73 20 6e 6f 74 20 0a 2a  ands does not .*
1a020 2a 20 69 6e 63 6c 75 64 65 20 6f 75 74 70 75 74  * include output
1a030 20 66 6f 72 20 61 6e 79 20 6f 70 65 72 61 74 69   for any operati
1a040 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79  ons performed by
1a050 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1a060 73 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74 69 6f  s. This.** optio
1a070 6e 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  n is used to set
1a080 20 6f 72 20 63 6c 65 61 72 20 28 74 68 65 20 64   or clear (the d
1a090 65 66 61 75 6c 74 29 20 61 20 66 6c 61 67 20 74  efault) a flag t
1a0a0 68 61 74 20 67 6f 76 65 72 6e 73 20 74 68 69 73  hat governs this
1a0b0 0a 2a 2a 20 62 65 68 61 76 69 6f 72 2e 20 54 68  .** behavior. Th
1a0c0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1a0d0 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73  r passed to this
1a0e0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
1a0f0 20 69 6e 74 65 67 65 72 20 2d 0a 2a 2a 20 70 6f   integer -.** po
1a100 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
1a110 20 6f 75 74 70 75 74 20 66 6f 72 20 74 72 69 67   output for trig
1a120 67 65 72 20 70 72 6f 67 72 61 6d 73 2c 20 6f 72  ger programs, or
1a130 20 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65   zero to disable
1a140 20 69 74 2c 0a 2a 2a 20 6f 72 20 6e 65 67 61 74   it,.** or negat
1a150 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
1a160 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67   setting unchang
1a170 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
1a180 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
1a190 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
1a1a0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
1a1b0 68 20 69 73 20 77 72 69 74 74 65 6e 20 0a 2a 2a  h is written .**
1a1c0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
1a1d0 61 74 65 20 77 68 65 74 68 65 72 20 6f 75 74 70  ate whether outp
1a1e0 75 74 2d 66 6f 72 2d 74 72 69 67 67 65 72 73 20  ut-for-triggers 
1a1f0 68 61 73 20 62 65 65 6e 20 64 69 73 61 62 6c 65  has been disable
1a200 64 20 2d 20 30 20 69 66 20 0a 2a 2a 20 69 74 20  d - 0 if .** it 
1a210 69 73 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c  is not disabled,
1a220 20 31 20 69 66 20 69 74 20 69 73 2e 20 20 0a 2a   1 if it is.  .*
1a230 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
1a240 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
1a250 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 45  G_RESET_DATABASE
1a260 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 53 65  </dt>.** <dd> Se
1a270 74 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43  t the SQLITE_DBC
1a280 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41  ONFIG_RESET_DATA
1a290 42 41 53 45 20 66 6c 61 67 20 61 6e 64 20 74 68  BASE flag and th
1a2a0 65 6e 20 72 75 6e 0a 2a 2a 20 5b 56 41 43 55 55  en run.** [VACUU
1a2b0 4d 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72  M] in order to r
1a2c0 65 73 65 74 20 61 20 64 61 74 61 62 61 73 65 20  eset a database 
1a2d0 62 61 63 6b 20 74 6f 20 61 6e 20 65 6d 70 74 79  back to an empty
1a2e0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 77 69 74   database.** wit
1a2f0 68 20 6e 6f 20 73 63 68 65 6d 61 20 61 6e 64 20  h no schema and 
1a300 6e 6f 20 63 6f 6e 74 65 6e 74 2e 20 54 68 65 20  no content. The 
1a310 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 63 65 73  following proces
1a320 73 20 77 6f 72 6b 73 20 65 76 65 6e 20 66 6f 72  s works even for
1a330 0a 2a 2a 20 61 20 62 61 64 6c 79 20 63 6f 72 72  .** a badly corr
1a340 75 70 74 65 64 20 64 61 74 61 62 61 73 65 20 66  upted database f
1a350 69 6c 65 3a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  ile:.** <ol>.** 
1a360 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 64 62 5f  <li> sqlite3_db_
1a370 63 6f 6e 66 69 67 28 64 62 2c 20 53 51 4c 49 54  config(db, SQLIT
1a380 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54  E_DBCONFIG_RESET
1a390 5f 44 41 54 41 42 41 53 45 2c 20 31 2c 20 30 29  _DATABASE, 1, 0)
1a3a0 3b 0a 2a 2a 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  ;.** <li> [sqlit
1a3b0 65 33 5f 65 78 65 63 5d 28 64 62 2c 20 22 5b 56  e3_exec](db, "[V
1a3c0 41 43 55 55 4d 5d 22 2c 20 30 2c 20 30 2c 20 30  ACUUM]", 0, 0, 0
1a3d0 29 3b 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74  );.** <li> sqlit
1a3e0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 64 62 2c  e3_db_config(db,
1a3f0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1a400 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 2c  _RESET_DATABASE,
1a410 20 30 2c 20 30 29 3b 0a 2a 2a 20 3c 2f 6f 6c 3e   0, 0);.** </ol>
1a420 0a 2a 2a 20 42 65 63 61 75 73 65 20 72 65 73 65  .** Because rese
1a430 74 74 69 6e 67 20 61 20 64 61 74 61 62 61 73 65  tting a database
1a440 20 69 73 20 64 65 73 74 72 75 63 74 69 76 65 20   is destructive 
1a450 61 6e 64 20 69 72 72 65 76 65 72 73 69 62 6c 65  and irreversible
1a460 2c 20 74 68 65 0a 2a 2a 20 70 72 6f 63 65 73 73  , the.** process
1a470 20 72 65 71 75 69 72 65 73 20 74 68 65 20 75 73   requires the us
1a480 65 20 6f 66 20 74 68 69 73 20 6f 62 73 63 75 72  e of this obscur
1a490 65 20 41 50 49 20 61 6e 64 20 6d 75 6c 74 69 70  e API and multip
1a4a0 6c 65 20 73 74 65 70 73 20 74 6f 20 68 65 6c 70  le steps to help
1a4b0 0a 2a 2a 20 65 6e 73 75 72 65 20 74 68 61 74 20  .** ensure that 
1a4c0 69 74 20 64 6f 65 73 20 6e 6f 74 20 68 61 70 70  it does not happ
1a4d0 65 6e 20 62 79 20 61 63 63 69 64 65 6e 74 2e 0a  en by accident..
1a4e0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c  ** </dd>.** </dl
1a4f0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
1a500 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49  ITE_DBCONFIG_MAI
1a510 4e 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20  NDBNAME         
1a520 20 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74     1000 /* const
1a530 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e   char* */.#defin
1a540 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1a550 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20  G_LOOKASIDE     
1a560 20 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20          1001 /* 
1a570 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
1a580 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a590 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
1a5a0 46 4b 45 59 20 20 20 20 20 20 20 20 20 20 20 31  FKEY           1
1a5b0 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  002 /* int int* 
1a5c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a5d0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
1a5e0 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
1a5f0 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74   1003 /* int int
1a600 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
1a610 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
1a620 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a  BLE_FTS3_TOKENIZ
1a630 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69  ER 1004 /* int i
1a640 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
1a650 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
1a660 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e  NABLE_LOAD_EXTEN
1a670 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74  SION 1005 /* int
1a680 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
1a690 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1a6a0 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53  _NO_CKPT_ON_CLOS
1a6b0 45 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20 69  E      1006 /* i
1a6c0 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
1a6d0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
1a6e0 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 20  IG_ENABLE_QPSG  
1a6f0 20 20 20 20 20 20 20 20 20 31 30 30 37 20 2f 2a           1007 /*
1a700 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
1a710 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
1a720 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50  NFIG_TRIGGER_EQP
1a730 20 20 20 20 20 20 20 20 20 20 20 31 30 30 38 20             1008 
1a740 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
1a750 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
1a760 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54  CONFIG_RESET_DAT
1a770 41 42 41 53 45 20 20 20 20 20 20 20 20 31 30 30  ABASE        100
1a780 39 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  9 /* int int* */
1a790 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a7a0 44 42 43 4f 4e 46 49 47 5f 4d 41 58 20 20 20 20  DBCONFIG_MAX    
1a7b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
1a7c0 30 30 39 20 2f 2a 20 4c 61 72 67 65 73 74 20 44  009 /* Largest D
1a7d0 42 43 4f 4e 46 49 47 20 2a 2f 0a 0a 2f 2a 0a 2a  BCONFIG */../*.*
1a7e0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
1a7f0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
1a800 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
1a810 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  des.** METHOD: s
1a820 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1a830 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
1a840 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
1a850 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
1a860 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
1a870 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
1a880 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
1a890 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
1a8a0 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
1a8b0 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
1a8c0 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
1a8d0 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
1a8e0 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
1a8f0 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ty..*/.int sqlit
1a900 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
1a910 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
1a920 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
1a930 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a940 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
1a950 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
1a960 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  ite3.**.** ^Each
1a970 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53   entry in most S
1a980 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78  QLite tables (ex
1a990 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55  cept for [WITHOU
1a9a0 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29  T ROWID] tables)
1a9b0 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65  .** has a unique
1a9c0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a   64-bit signed.*
1a9d0 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61  * integer key ca
1a9e0 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20  lled the [ROWID 
1a9f0 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65  | "rowid"]. ^The
1aa00 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
1aa10 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
1aa20 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
1aa30 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
1aa40 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
1aa50 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
1aa60 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
1aa70 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
1aa80 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
1aa90 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e  lared columns. ^
1aaa0 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
1aab0 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
1aac0 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52  type [INTEGER PR
1aad0 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20  IMARY KEY] then 
1aae0 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  that column.** i
1aaf0 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20  s another alias 
1ab00 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a  for the rowid..*
1ab10 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1ab20 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
1ab30 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65  wid(D) interface
1ab40 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72 6e 73   usually returns
1ab50 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a   the [rowid] of.
1ab60 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  ** the most rece
1ab70 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  nt successful [I
1ab80 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f  NSERT] into a ro
1ab90 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69  wid table or [vi
1aba0 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20  rtual table].** 
1abb0 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  on database conn
1abc0 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72  ection D. ^Inser
1abd0 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54  ts into [WITHOUT
1abe0 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61   ROWID] tables a
1abf0 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64  re not.** record
1ac00 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63 65  ed. ^If no succe
1ac10 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20  ssful [INSERT]s 
1ac20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65  into rowid table
1ac30 73 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  s have ever occu
1ac40 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20  rred .** on the 
1ac50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ac60 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c 69  ion D, then sqli
1ac70 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1ac80 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73  rowid(D) returns
1ac90 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a   .** zero..**.**
1aca0 20 41 73 20 77 65 6c 6c 20 61 73 20 62 65 69 6e   As well as bein
1acb0 67 20 73 65 74 20 61 75 74 6f 6d 61 74 69 63 61  g set automatica
1acc0 6c 6c 79 20 61 73 20 72 6f 77 73 20 61 72 65 20  lly as rows are 
1acd0 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 64 61  inserted into da
1ace0 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73  tabase.** tables
1acf0 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
1ad00 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e  rned by this fun
1ad10 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 74  ction may be set
1ad20 20 65 78 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a   explicitly by.*
1ad30 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c  * [sqlite3_set_l
1ad40 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1ad50 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76  ()].**.** Some v
1ad60 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
1ad70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
1ad80 20 49 4e 53 45 52 54 20 72 6f 77 73 20 69 6e 74   INSERT rows int
1ad90 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 61  o rowid tables a
1ada0 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d  s.** part of com
1adb0 6d 69 74 74 69 6e 67 20 61 20 74 72 61 6e 73 61  mitting a transa
1adc0 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66  ction (e.g. to f
1add0 6c 75 73 68 20 64 61 74 61 20 61 63 63 75 6d 75  lush data accumu
1ade0 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a  lated in memory.
1adf0 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20  ** to disk). In 
1ae00 74 68 69 73 20 63 61 73 65 20 73 75 62 73 65 71  this case subseq
1ae10 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74 68  uent calls to th
1ae20 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
1ae30 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20  rn the rowid.** 
1ae40 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1ae50 74 68 65 73 65 20 69 6e 74 65 72 6e 61 6c 20 49  these internal I
1ae60 4e 53 45 52 54 20 6f 70 65 72 61 74 69 6f 6e 73  NSERT operations
1ae70 2c 20 77 68 69 63 68 20 6c 65 61 64 73 20 74 6f  , which leads to
1ae80 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76 65   .** unintuitive
1ae90 20 72 65 73 75 6c 74 73 2e 20 56 69 72 74 75 61   results. Virtua
1aea0 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
1aeb0 74 61 74 69 6f 6e 73 20 74 68 61 74 20 64 6f 20  tations that do 
1aec0 77 72 69 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a  write to rowid.*
1aed0 2a 20 74 61 62 6c 65 73 20 69 6e 20 74 68 69 73  * tables in this
1aee0 20 77 61 79 20 63 61 6e 20 61 76 6f 69 64 20 74   way can avoid t
1aef0 68 69 73 20 70 72 6f 62 6c 65 6d 20 62 79 20 72  his problem by r
1af00 65 73 74 6f 72 69 6e 67 20 74 68 65 20 6f 72 69  estoring the ori
1af10 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20  ginal .** rowid 
1af20 76 61 6c 75 65 20 75 73 69 6e 67 20 5b 73 71 6c  value using [sql
1af30 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
1af40 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 62 65  sert_rowid()] be
1af50 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 20 0a  fore returning .
1af60 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68  ** control to th
1af70 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  e user..**.** ^(
1af80 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
1af90 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
1afa0 72 69 67 67 65 72 20 74 68 65 6e 20 74 68 69 73  rigger then this
1afb0 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a   routine will .*
1afc0 2a 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f  * return the [ro
1afd0 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65  wid] of the inse
1afe0 72 74 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67  rted row as long
1aff0 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
1b000 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20  is .** running. 
1b010 4f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  Once the trigger
1b020 20 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74   program ends, t
1b030 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1b040 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  d .** by this ro
1b050 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
1b060 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66   what it was bef
1b070 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
1b080 77 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a  was fired.)^.**.
1b090 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
1b0a0 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
1b0b0 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
1b0c0 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
1b0d0 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
1b0e0 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
1b0f0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
1b100 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1b110 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
1b120 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
1b130 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
1b140 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
1b150 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
1b160 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
1b170 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
1b180 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
1b190 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
1b1a0 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
1b1b0 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
1b1c0 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
1b1d0 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
1b1e0 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
1b1f0 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
1b200 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
1b210 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
1b220 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
1b230 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
1b240 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
1b250 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
1b260 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
1b270 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
1b280 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
1b290 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
1b2a0 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
1b2b0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
1b2c0 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
1b2d0 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
1b2e0 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
1b2f0 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
1b300 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
1b310 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
1b320 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
1b330 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
1b340 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
1b350 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
1b360 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
1b370 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
1b380 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
1b390 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1b3a0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
1b3b0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
1b3c0 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
1b3d0 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
1b3e0 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
1b3f0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1b400 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
1b410 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
1b420 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
1b430 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
1b440 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
1b450 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
1b460 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
1b470 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
1b480 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
1b490 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
1b4a0 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
1b4b0 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
1b4c0 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
1b4d0 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
1b4e0 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
1b4f0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
1b500 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  wid]..*/.sqlite3
1b510 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
1b520 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1b530 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1b540 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
1b550 20 74 68 65 20 4c 61 73 74 20 49 6e 73 65 72 74   the Last Insert
1b560 20 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a   Rowid value..**
1b570 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1b580 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1b590 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65  e3_set_last_inse
1b5a0 72 74 5f 72 6f 77 69 64 28 44 2c 20 52 29 20 6d  rt_rowid(D, R) m
1b5b0 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65  ethod allows the
1b5c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a   application to.
1b5d0 2a 2a 20 73 65 74 20 74 68 65 20 76 61 6c 75 65  ** set the value
1b5e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 63 61 6c   returned by cal
1b5f0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61 73  ling sqlite3_las
1b600 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
1b610 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f  ) to R .** witho
1b620 75 74 20 69 6e 73 65 72 74 69 6e 67 20 61 20 72  ut inserting a r
1b630 6f 77 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  ow into the data
1b640 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  base..*/.void sq
1b650 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69  lite3_set_last_i
1b660 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
1b670 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  te3*,sqlite3_int
1b680 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  64);../*.** CAPI
1b690 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
1b6a0 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
1b6b0 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f  odified.** METHO
1b6c0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1b6d0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
1b6e0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
1b6f0 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66  er of rows modif
1b700 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ied, inserted or
1b710 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74  .** deleted by t
1b720 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
1b730 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
1b740 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
1b750 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
1b760 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
1b770 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63   connection spec
1b780 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c  ified by the onl
1b790 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  y parameter..** 
1b7a0 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f  ^Executing any o
1b7b0 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c  ther type of SQL
1b7c0 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
1b7d0 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76  not modify the v
1b7e0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
1b7f0 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f   by this functio
1b800 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63  n..**.** ^Only c
1b810 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65  hanges made dire
1b820 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45  ctly by the INSE
1b830 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
1b840 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61  LETE statement a
1b850 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
1b860 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61   - auxiliary cha
1b870 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
1b880 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
1b890 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20   triggers], .** 
1b8a0 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
1b8b0 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43  ions] or [REPLAC
1b8c0 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  E] constraint re
1b8d0 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74  solution are not
1b8e0 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a   counted..** .**
1b8f0 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69   Changes to a vi
1b900 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
1b910 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b  rcepted by .** [
1b920 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
1b930 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20  er | INSTEAD OF 
1b940 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f  triggers] are no
1b950 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20  t counted. ^The 
1b960 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e  value .** return
1b970 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68  ed by sqlite3_ch
1b980 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74  anges() immediat
1b990 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53  ely after an INS
1b9a0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a  ERT, UPDATE or .
1b9b0 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  ** DELETE statem
1b9c0 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65  ent run on a vie
1b9d0 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  w is always zero
1b9e0 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d  . Only changes m
1b9f0 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20  ade to real .** 
1ba00 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74  tables are count
1ba10 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73  ed..**.** Things
1ba20 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69   are more compli
1ba30 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c  cated if the sql
1ba40 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66  ite3_changes() f
1ba50 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78  unction is.** ex
1ba60 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74  ecuted while a t
1ba70 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69  rigger program i
1ba80 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20  s running. This 
1ba90 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68  may happen if th
1baa0 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65  e.** program use
1bab0 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  s the [changes()
1bac0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20   SQL function], 
1bad0 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72  or if some other
1bae0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
1baf0 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71  ction invokes sq
1bb00 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
1bb10 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74  directly. Essent
1bb20 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75  ially:.** .** <u
1bb30 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42  l>.**   <li> ^(B
1bb40 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61  efore entering a
1bb50 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1bb60 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1bb70 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  ned by.**       
1bb80 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1bb90 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73  () function is s
1bba0 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20  aved. After the 
1bbb0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
1bbc0 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66  .**        has f
1bbd0 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69  inished, the ori
1bbe0 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72  ginal value is r
1bbf0 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a  estored.)^.** .*
1bc00 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69  *   <li> ^(Withi
1bc10 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  n a trigger prog
1bc20 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c  ram each INSERT,
1bc30 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45   UPDATE and DELE
1bc40 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74  TE .**        st
1bc50 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65  atement sets the
1bc60 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1bc70 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  by sqlite3_chang
1bc80 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  es() .**        
1bc90 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  upon completion 
1bca0 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f  as normal. Of co
1bcb0 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65  urse, this value
1bcc0 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64   will not includ
1bcd0 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79  e .**        any
1bce0 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d   changes perform
1bcf0 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65  ed by sub-trigge
1bd00 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74  rs, as the sqlit
1bd10 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a  e3_changes() .**
1bd20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69          value wi
1bd30 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20  ll be saved and 
1bd40 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65  restored after e
1bd50 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20  ach sub-trigger 
1bd60 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f  has run.)^.** </
1bd70 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73  ul>.** .** ^This
1bd80 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74   means that if t
1bd90 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c  he changes() SQL
1bda0 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69   function (or si
1bdb0 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a  milar) is used.*
1bdc0 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49  * by the first I
1bdd0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
1bde0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
1bdf0 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
1be00 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72  er, it .** retur
1be10 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20  ns the value as 
1be20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c  set when the cal
1be30 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62  ling statement b
1be40 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a  egan executing..
1be50 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65  ** ^If it is use
1be60 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
1be70 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75  or subsequent su
1be80 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ch statement wit
1be90 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a  hin a trigger .*
1bea0 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76  * program, the v
1beb0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65  alue returned re
1bec0 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65  flects the numbe
1bed0 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
1bee0 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72  ed by the .** pr
1bef0 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55  evious INSERT, U
1bf00 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
1bf10 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
1bf20 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
1bf30 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
1bf40 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
1bf50 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
1bf60 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
1bf70 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
1bf80 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
1bf90 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
1bfa0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
1bfb0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
1bfc0 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
1bfd0 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
1bfe0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1bff0 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
1c000 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1c010 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
1c020 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
1c030 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
1c040 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
1c050 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
1c060 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
1c070 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
1c080 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c090 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
1c0a0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
1c0b0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1c0c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
1c0d0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1c0e0 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
1c0f0 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c  f rows inserted,
1c100 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20   modified or.** 
1c110 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b  deleted by all [
1c120 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45  INSERT], [UPDATE
1c130 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
1c140 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74  atements complet
1c150 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  ed.** since the 
1c160 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c170 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20  ion was opened, 
1c180 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20  including those 
1c190 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70  executed as.** p
1c1a0 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70  art of trigger p
1c1b0 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74  rograms. ^Execut
1c1c0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79  ing any other ty
1c1d0 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  pe of SQL statem
1c1e0 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ent.** does not 
1c1f0 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65  affect the value
1c200 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1c210 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1c220 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68  es()..** .** ^Ch
1c230 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61  anges made as pa
1c240 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b  rt of [foreign k
1c250 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
1c260 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a  included in the.
1c270 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68  ** count, but th
1c280 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74  ose made as part
1c290 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73   of REPLACE cons
1c2a0 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
1c2b0 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43  n are.** not. ^C
1c2c0 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
1c2d0 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63   that are interc
1c2e0 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44  epted by INSTEAD
1c2f0 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a   OF triggers .**
1c300 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
1c310 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73  ..** .** See als
1c320 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
1c330 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
1c340 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
1c350 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
1c360 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74  a], and the [tot
1c370 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c  al_changes() SQL
1c380 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
1c390 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
1c3a0 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
1c3b0 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
1c3c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c3d0 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
1c3e0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1c3f0 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
1c400 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
1c410 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
1c420 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
1c430 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
1c440 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
1c450 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1c460 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1c470 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
1c480 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
1c490 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45  ning Query.** ME
1c4a0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1c4b0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
1c4c0 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
1c4d0 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
1c4e0 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
1c4f0 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
1c500 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
1c510 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
1c520 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
1c530 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
1c540 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
1c550 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
1c560 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
1c570 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
1c580 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
1c590 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
1c5a0 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
1c5b0 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
1c5c0 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
1c5d0 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
1c5e0 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
1c5f0 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
1c600 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
1c610 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
1c620 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
1c630 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
1c640 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
1c650 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
1c660 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
1c670 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
1c680 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1c690 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
1c6a0 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
1c6b0 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
1c6c0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1c6d0 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
1c6e0 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
1c6f0 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
1c700 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
1c710 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
1c720 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
1c730 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
1c740 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
1c750 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
1c760 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
1c770 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
1c780 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
1c790 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
1c7a0 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
1c7b0 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
1c7c0 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
1c7d0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
1c7e0 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
1c7f0 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
1c800 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
1c810 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
1c820 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
1c830 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
1c840 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
1c850 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
1c860 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
1c870 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
1c880 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
1c890 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
1c8a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
1c8b0 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
1c8c0 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
1c8d0 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
1c8e0 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
1c8f0 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
1c900 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c910 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
1c920 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
1c930 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
1c940 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
1c950 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
1c960 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1c970 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
1c980 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
1c990 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
1c9a0 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
1c9b0 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
1c9c0 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
1c9d0 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
1c9e0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1c9f0 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
1ca00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1ca10 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1ca20 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
1ca30 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
1ca40 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
1ca50 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
1ca60 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
1ca70 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1ca80 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
1ca90 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1caa0 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
1cab0 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
1cac0 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
1cad0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
1cae0 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
1caf0 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
1cb00 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1cb10 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1cb20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
1cb30 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
1cb40 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76  ll returns..*/.v
1cb50 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
1cb60 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
1cb70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1cb80 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
1cb90 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
1cba0 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
1cbb0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1cbc0 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
1cbd0 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
1cbe0 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
1cbf0 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
1cc00 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
1cc10 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
1cc20 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
1cc30 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
1cc40 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
1cc50 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
1cc60 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
1cc70 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
1cc80 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
1cc90 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
1cca0 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
1ccb0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1ccc0 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
1ccd0 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
1cce0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
1ccf0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
1cd00 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
1cd10 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
1cd20 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
1cd30 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
1cd40 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
1cd50 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
1cd60 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
1cd70 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
1cd80 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
1cd90 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
1cda0 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
1cdb0 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
1cdc0 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
1cdd0 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
1cde0 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
1cdf0 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
1ce00 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
1ce10 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
1ce20 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
1ce30 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
1ce40 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
1ce50 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
1ce60 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
1ce70 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
1ce80 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
1ce90 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
1cea0 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
1ceb0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1cec0 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
1ced0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
1cee0 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
1cef0 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
1cf00 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
1cf10 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
1cf20 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
1cf30 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1cf40 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
1cf50 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
1cf60 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
1cf70 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
1cf80 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
1cf90 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
1cfa0 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
1cfb0 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
1cfc0 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
1cfd0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
1cfe0 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
1cff0 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
1d000 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
1d010 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
1d020 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
1d030 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
1d040 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
1d050 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
1d060 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
1d070 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
1d080 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
1d090 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
1d0a0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
1d0b0 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
1d0c0 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
1d0d0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1d0e0 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
1d0f0 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
1d100 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
1d110 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1d120 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
1d130 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1d140 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
1d150 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
1d160 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
1d170 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
1d180 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1d190 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
1d1a0 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
1d1b0 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
1d1c0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1d1d0 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
1d1e0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
1d1f0 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
1d200 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
1d210 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1d220 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
1d230 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
1d240 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
1d250 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73  * KEYWORDS: {bus
1d260 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
1d270 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65  ck} {busy handle
1d280 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
1d290 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
1d2a0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1d2b0 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75  ndler(D,X,P) rou
1d2c0 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
1d2d0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a  back function X.
1d2e0 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  ** that might be
1d2f0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
1d300 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
1d310 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
1d320 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
1d330 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  s a database tab
1d340 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  le associated wi
1d350 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  th.** [database 
1d360 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68  connection] D wh
1d370 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  en another threa
1d380 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
1d390 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f  has the table lo
1d3a0 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  cked..** The sql
1d3b0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1d3c0 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  r() interface is
1d3d0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1d3e0 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nt.** [sqlite3_b
1d3f0 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61  usy_timeout()] a
1d400 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  nd [PRAGMA busy_
1d410 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20  timeout]..**.** 
1d420 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
1d430 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
1d440 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
1d450 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
1d460 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
1d470 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
1d480 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
1d490 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
1d4a0 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
1d4b0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
1d4c0 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
1d4d0 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
1d4e0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1d4f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1d500 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
1d510 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
1d520 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
1d530 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
1d540 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
1d550 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
1d560 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
1d570 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1d580 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
1d590 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
1d5a0 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
1d5b0 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
1d5c0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1d5d0 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
1d5e0 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20  oked previously 
1d5f0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63  for the same loc
1d600 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
1d610 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
1d620 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
1d630 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
1d640 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
1d650 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
1d660 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
1d670 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
1d680 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ] is returned.**
1d690 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1d6a0 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
1d6b0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1d6c0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
1d6d0 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
1d6e0 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  ** is made to ac
1d6f0 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
1d700 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  e and the cycle 
1d710 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
1d720 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
1d730 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
1d740 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
1d750 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
1d760 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
1d770 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
1d780 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
1d790 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
1d7a0 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
1d7b0 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
1d7c0 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
1d7d0 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
1d7e0 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
1d7f0 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
1d800 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74  TE_BUSY].** to t
1d810 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
1d820 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
1d830 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20  ng the .** busy 
1d840 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
1d850 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
1d860 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
1d870 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
1d880 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
1d890 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
1d8a0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
1d8b0 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
1d8c0 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
1d8d0 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
1d8e0 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
1d8f0 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
1d900 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
1d910 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
1d920 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
1d930 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
1d940 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
1d950 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1d960 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
1d970 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
1d980 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
1d990 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
1d9a0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1d9b0 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
1d9c0 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
1d9d0 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
1d9e0 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
1d9f0 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
1da00 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
1da10 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
1da20 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1da30 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
1da40 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
1da50 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
1da60 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
1da70 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
1da80 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
1da90 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
1daa0 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
1dab0 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
1dac0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1dad0 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
1dae0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
1daf0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1db00 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1db10 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
1db20 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
1db30 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1db40 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
1db50 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
1db60 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
1db70 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1db80 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
1db90 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
1dba0 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1dbb0 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72  timeout()].** or
1dbc0 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41   evaluating [PRA
1dbd0 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1dbe0 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20  =N] will change 
1dbf0 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  the.** busy hand
1dc00 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65  ler and thus cle
1dc10 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c  ar any previousl
1dc20 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c  y set busy handl
1dc30 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
1dc40 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
1dc50 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
1dc60 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
1dc70 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
1dc80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1dc90 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1dca0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
1dcb0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a  In other words,.
1dcc0 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1dcd0 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ler is not reent
1dce0 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20  rant.  Any such 
1dcf0 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
1dd00 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
1dd10 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
1dd20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
1dd30 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
1dd40 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1dd50 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
1dd60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1dd70 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1dd80 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
1dd90 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1dda0 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
1ddb0 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64  te3*,int(*)(void
1ddc0 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a  *,int),void*);..
1ddd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1dde0 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
1ddf0 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ut.** METHOD: sq
1de00 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1de10 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
1de20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1de30 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
1de40 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
1de50 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
1de60 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
1de70 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
1de80 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54  e is locked.  ^T
1de90 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
1dea0 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
1deb0 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
1dec0 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
1ded0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1dee0 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
1def0 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65  umulated.  ^Afte
1df00 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  r at least "ms" 
1df10 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
1df20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
1df30 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
1df40 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
1df50 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1df60 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
1df70 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a  QLITE_BUSY]..**.
1df80 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
1df90 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
1dfa0 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
1dfb0 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
1dfc0 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
1dfd0 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
1dfe0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
1dff0 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1e000 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1e010 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
1e020 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1e030 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
1e040 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  t any given mome
1e050 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
1e060 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
1e070 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
1e080 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
1e090 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
1e0a0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
1e0b0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
1e0c0 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
1e0d0 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
1e0e0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ed.)^.**.** See 
1e0f0 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62  also:  [PRAGMA b
1e100 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a  usy_timeout].*/.
1e110 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
1e120 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
1e130 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
1e140 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
1e150 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
1e160 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
1e170 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  eries.** METHOD:
1e180 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
1e190 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20  his is a legacy 
1e1a0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69  interface that i
1e1b0 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20  s preserved for 
1e1c0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1e1d0 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20  ibility..** Use 
1e1e0 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
1e1f0 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65  e is not recomme
1e200 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69  nded..**.** Defi
1e210 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
1e220 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
1e230 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
1e240 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
1e250 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
1e260 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
1e270 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
1e280 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
1e290 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
1e2a0 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
1e2b0 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
1e2c0 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
1e2d0 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
1e2e0 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
1e2f0 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
1e300 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
1e310 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
1e320 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
1e330 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1e340 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
1e350 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
1e360 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
1e370 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
1e380 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
1e390 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
1e3a0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1e3b0 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
1e3c0 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
1e3d0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
1e3e0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
1e3f0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
1e400 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
1e410 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
1e420 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
1e430 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
1e440 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
1e450 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1e460 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
1e470 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
1e480 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
1e490 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
1e4a0 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
1e4b0 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
1e4c0 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
1e4d0 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
1e4e0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
1e4f0 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
1e500 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
1e510 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
1e520 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
1e530 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
1e540 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1e550 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
1e560 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
1e570 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
1e580 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
1e590 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
1e5a0 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
1e5b0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
1e5c0 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
1e5d0 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
1e5e0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1e5f0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1e600 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
1e610 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
1e620 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1e630 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  le()]..**.** ^(A
1e640 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
1e650 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1e660 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
1e670 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
1e680 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
1e690 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1e6a0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
1e6b0 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
1e6c0 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
1e6d0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1e6e0 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
1e6f0 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
1e700 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
1e710 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
1e720 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
1e730 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
1e740 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1e750 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
1e760 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
1e770 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
1e780 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
1e790 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
1e7a0 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
1e7b0 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
1e7c0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
1e7d0 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
1e7e0 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
1e7f0 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
1e800 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
1e810 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
1e820 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1e830 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1e840 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
1e850 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1e860 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
1e870 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
1e880 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
1e890 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
1e8a0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1e8b0 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
1e8c0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1e8d0 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
1e8e0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1e8f0 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
1e900 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1e910 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
1e920 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
1e930 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
1e940 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
1e950 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1e960 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
1e970 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1e980 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
1e990 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
1e9a0 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
1e9b0 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
1e9c0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
1e9d0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1e9e0 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
1e9f0 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
1ea00 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  er and returns a
1ea10 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
1ea20 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
1ea30 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
1ea40 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1ea50 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c  * After the appl
1ea60 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  ication has fini
1ea70 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65  shed with the re
1ea80 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65  sult from sqlite
1ea90 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a  3_get_table(),.*
1eaa0 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74  * it must pass t
1eab0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1eac0 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
1ead0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
1eae0 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
1eaf0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1eb00 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
1eb10 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
1eb20 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
1eb30 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1eb40 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
1eb50 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
1eb60 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
1eb70 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
1eb80 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
1eb90 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
1eba0 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
1ebb0 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
1ebc0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
1ebd0 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
1ebe0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
1ebf0 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
1ec00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1ec10 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1ec20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
1ec30 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
1ec40 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
1ec50 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1ec60 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
1ec70 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
1ec80 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
1ec90 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
1eca0 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
1ecb0 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
1ecc0 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
1ecd0 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
1ece0 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
1ecf0 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
1ed00 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
1ed10 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
1ed20 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
1ed30 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
1ed40 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
1ed50 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
1ed60 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
1ed70 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
1ed80 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
1ed90 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1eda0 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
1edb0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
1edc0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
1edd0 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
1ede0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1edf0 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
1ee00 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
1ee10 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1ee20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
1ee30 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
1ee40 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
1ee50 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
1ee60 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
1ee70 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
1ee80 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
1ee90 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
1eea0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
1eeb0 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
1eec0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1eed0 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
1eee0 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
1eef0 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
1ef00 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
1ef10 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
1ef20 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
1ef30 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1ef40 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
1ef50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ef60 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
1ef70 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
1ef80 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
1ef90 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1efa0 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
1efb0 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
1efc0 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
1efd0 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
1efe0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1eff0 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
1f000 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d  nes understand m
1f010 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f  ost of the commo
1f020 6e 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  n formatting opt
1f030 69 6f 6e 73 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  ions from.** the
1f040 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72   standard librar
1f050 79 20 70 72 69 6e 74 66 28 29 20 0a 2a 2a 20 70  y printf() .** p
1f060 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  lus some additio
1f070 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64  nal non-standard
1f080 20 66 6f 72 6d 61 74 73 20 28 5b 25 71 5d 2c 20   formats ([%q], 
1f090 5b 25 51 5d 2c 20 5b 25 77 5d 2c 20 61 6e 64 20  [%Q], [%w], and 
1f0a0 5b 25 7a 5d 29 2e 0a 2a 2a 20 53 65 65 20 74 68  [%z])..** See th
1f0b0 65 20 5b 62 75 69 6c 74 2d 69 6e 20 70 72 69 6e  e [built-in prin
1f0c0 74 66 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74  tf()] documentat
1f0d0 69 6f 6e 20 66 6f 72 20 64 65 74 61 69 6c 73 2e  ion for details.
1f0e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1f0f0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
1f100 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e  d sqlite3_vmprin
1f110 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72  tf() routines wr
1f120 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73  ite their.** res
1f130 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ults into memory
1f140 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
1f150 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1f160 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
1f170 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
1f180 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
1f190 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
1f1a0 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
1f1b0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e  ite3_free()].  ^
1f1c0 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
1f1d0 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
1f1e0 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
1f1f0 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d 20 69  e3_malloc64()] i
1f200 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
1f210 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
1f220 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
1f230 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
1f240 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ng..**.** ^(The 
1f250 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1f260 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
1f270 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e  milar to "snprin
1f280 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68  tf()" from.** th
1f290 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
1f2a0 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c  rary.  The resul
1f2b0 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  t is written int
1f2c0 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20  o the.** buffer 
1f2d0 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20  supplied as the 
1f2e0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1f2f0 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67   whose size is g
1f300 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66  iven by.** the f
1f310 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
1f320 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72  Note that the or
1f330 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  der of the.** fi
1f340 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65  rst two paramete
1f350 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66  rs is reversed f
1f360 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29  rom snprintf().)
1f370 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a  ^  This is an.**
1f380 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69   historical acci
1f390 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74  dent that cannot
1f3a0 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75   be fixed withou
1f3b0 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61  t breaking.** ba
1f3c0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1f3d0 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61  ility.  ^(Note a
1f3e0 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
1f3f0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
1f400 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1f410 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
1f420 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
1f430 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
1f440 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
1f450 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
1f460 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64  buffer.)^  We ad
1f470 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
1f480 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
1f490 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
1f4a0 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
1f4b0 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
1f4c0 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
1f4d0 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
1f4e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
1f4f0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1f500 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
1f510 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
1f520 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ibility..**.** ^
1f530 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62  As long as the b
1f540 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72  uffer size is gr
1f550 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c  eater than zero,
1f560 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1f570 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  f().** guarantee
1f580 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65  s that the buffe
1f590 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  r is always zero
1f5a0 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
1f5b0 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
1f5c0 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65  meter "n" is the
1f5d0 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74   total size of t
1f5e0 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75  he buffer, inclu
1f5f0 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a  ding space for.*
1f600 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  * the zero termi
1f610 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c  nator.  So the l
1f620 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68  ongest string th
1f630 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65  at can be comple
1f640 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20  tely.** written 
1f650 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72  will be n-1 char
1f660 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  acters..**.** ^T
1f670 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  he sqlite3_vsnpr
1f680 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
1f690 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73  s a varargs vers
1f6a0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1f6b0 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a  nprintf()..**.**
1f6c0 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 62 75 69   See also:  [bui
1f6d0 6c 74 2d 69 6e 20 70 72 69 6e 74 66 28 29 5d 2c  lt-in printf()],
1f6e0 20 5b 70 72 69 6e 74 66 28 29 20 53 51 4c 20 66   [printf() SQL f
1f6f0 75 6e 63 74 69 6f 6e 5d 0a 2a 2f 0a 63 68 61 72  unction].*/.char
1f700 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
1f710 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
1f720 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
1f730 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
1f740 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1f750 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
1f760 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
1f770 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
1f780 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
1f790 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e  te3_vsnprintf(in
1f7a0 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
1f7b0 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a  ar*, va_list);..
1f7c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1f7d0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
1f7e0 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
1f7f0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
1f800 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
1f810 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
1f820 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
1f830 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
1f840 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
1f850 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
1f860 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
1f870 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
1f880 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
1f890 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
1f8a0 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
1f8b0 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
1f8c0 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
1f8d0 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
1f8e0 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
1f8f0 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
1f900 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1f910 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
1f920 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
1f930 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
1f940 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
1f950 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
1f960 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
1f970 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
1f980 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  r..** ^If sqlite
1f990 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
1f9a0 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
1f9b0 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
1f9c0 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
1f9d0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
1f9e0 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61  ter.  ^If the pa
1f9f0 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
1fa00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1fa10 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
1fa20 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
1fa30 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
1fa40 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
1fa50 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
1fa60 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1fa70 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72  4(N) routine wor
1fa80 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20  ks just like.** 
1fa90 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1faa0 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
1fab0 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36  is an unsigned 6
1fac0 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e  4-bit integer in
1fad0 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69  stead.** of a si
1fae0 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65  gned 32-bit inte
1faf0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ger..**.** ^Call
1fb00 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
1fb10 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
1fb20 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
1fb30 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1fb40 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1fb50 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1fb60 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
1fb70 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
1fb80 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
1fb90 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  used.  ^The sqli
1fba0 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
1fbb0 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
1fbc0 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
1fbd0 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
1fbe0 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
1fbf0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
1fc00 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1fc10 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
1fc20 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
1fc30 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
1fc40 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
1fc50 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
1fc60 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
1fc70 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
1fc80 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
1fc90 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
1fca0 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
1fcb0 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1fcc0 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
1fcd0 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
1fce0 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
1fcf0 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1fd00 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
1fd10 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
1fd20 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
1fd30 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
1fd40 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
1fd50 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
1fd60 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1fd70 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1fd80 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
1fd90 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1fda0 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69  3_realloc(X,N) i
1fdb0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
1fdc0 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a  s to resize a.**
1fdd0 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c   prior memory al
1fde0 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65  location X to be
1fdf0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1fe00 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20  s..** ^If the X 
1fe10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1fe20 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1fe30 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
1fe40 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
1fe50 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
1fe60 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
1fe70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1fe80 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68  oc(N)..** ^If th
1fe90 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e N parameter to
1fea0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1feb0 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72  (X,N) is zero or
1fec0 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
1fed0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
1fee0 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
1fef0 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
1ff00 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29   sqlite3_free(X)
1ff10 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65  ..** ^sqlite3_re
1ff20 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72  alloc(X,N) retur
1ff30 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1ff40 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
1ff50 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
1ff60 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
1ff70 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e  ze or NULL if in
1ff80 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
1ff90 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a  y is available..
1ffa0 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
1ffb0 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
1ffc0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
1ffd0 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
1ffe0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
1fff0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
20000 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
20010 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
20020 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
20030 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
20040 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65  loc(X,N) and the
20050 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
20060 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  n is freed..** ^
20070 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  If sqlite3_reall
20080 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20  oc(X,N) returns 
20090 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f  NULL and N is po
200a0 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  sitive, then the
200b0 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  .** prior alloca
200c0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65  tion is not free
200d0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
200e0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
200f0 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20  X,N) interfaces 
20100 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61  works the same a
20110 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61  s.** sqlite3_rea
20120 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74  lloc(X,N) except
20130 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d   that N is a 64-
20140 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
20150 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  eger instead.** 
20160 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e  of a 32-bit sign
20170 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  ed integer..**.*
20180 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d  * ^If X is a mem
20190 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70  ory allocation p
201a0 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
201b0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
201c0 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c  malloc(),.** sql
201d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c  ite3_malloc64(),
201e0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
201f0 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  (), or sqlite3_r
20200 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e  ealloc64(), then
20210 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
20220 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(X) returns the
20230 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65   size of that me
20240 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
20250 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68  in bytes..** ^Th
20260 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
20270 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a   by sqlite3_msiz
20280 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61  e(X) might be la
20290 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75  rger than the nu
202a0 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73  mber.** of bytes
202b0 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20   requested when 
202c0 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e  X was allocated.
202d0 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c    ^If X is a NUL
202e0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a  L pointer then.*
202f0 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  * sqlite3_msize(
20300 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  X) returns zero.
20310 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f    If X points to
20320 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20   something that 
20330 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65  is not.** the be
20340 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72  ginning of memor
20350 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72  y allocation, or
20360 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f   if it points to
20370 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76   a formerly.** v
20380 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  alid memory allo
20390 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20  cation that has 
203a0 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20  now been freed, 
203b0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
203c0 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  r.** of sqlite3_
203d0 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65  msize(X) is unde
203e0 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62  fined and possib
203f0 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
20400 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65  * ^The memory re
20410 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
20420 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69  3_malloc(), sqli
20430 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a  te3_realloc(),.*
20440 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
20450 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  64(), and sqlite
20460 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a  3_realloc64().**
20470 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
20480 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
20490 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
204a0 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20  y, or to a.** 4 
204b0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66  byte boundary if
204c0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42   the [SQLITE_4_B
204d0 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c  YTE_ALIGNED_MALL
204e0 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  OC] compile-time
204f0 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  .** option is us
20500 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  ed..**.** In SQL
20510 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
20520 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
20530 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
20540 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
20550 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
20560 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
20570 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
20580 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
20590 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
205a0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
205b0 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
205c0 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
205d0 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
205e0 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
205f0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
20600 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
20610 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69   used..**.** Pri
20620 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72  or to SQLite ver
20630 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65  sion 3.7.10, the
20640 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
20650 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
20660 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ed.** the system
20670 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
20680 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
20690 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
206a0 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
206b0 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
206c0 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
206d0 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
206e0 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
206f0 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
20700 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
20710 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
20720 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
20730 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
20740 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65  ors were detecte
20750 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77  d, but.** they w
20760 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  ere reported bac
20770 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
20780 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
20790 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
207a0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
207b0 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  NOMEM]..**.** Th
207c0 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
207d0 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
207e0 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
207f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
20800 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
20810 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
20820 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
20830 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
20840 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
20850 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
20860 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
20870 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
20880 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
20890 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
208a0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
208b0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
208c0 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
208d0 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
208e0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
208f0 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
20900 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
20910 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
20920 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
20930 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  loc()]..*/.void 
20940 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
20950 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
20960 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c  te3_malloc64(sql
20970 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f  ite3_uint64);.vo
20980 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
20990 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
209a0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
209b0 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20  ealloc64(void*, 
209c0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b  sqlite3_uint64);
209d0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
209e0 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74  ee(void*);.sqlit
209f0 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  e3_uint64 sqlite
20a00 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a  3_msize(void*);.
20a10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20a20 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
20a30 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a  r Statistics.**.
20a40 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
20a50 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
20a60 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
20a70 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
20a80 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
20a90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
20aa0 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
20ab0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
20ac0 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72  _realloc()].** r
20ad0 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66  outines, which f
20ae0 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  orm the built-in
20af0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
20b00 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a  on subsystem..**
20b10 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
20b20 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
20b30 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
20b40 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
20b50 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  ytes.** of memor
20b60 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73  y currently outs
20b70 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65  tanding (malloce
20b80 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
20b90 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
20ba0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
20bb0 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  ter()] routine r
20bc0 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d  eturns the maxim
20bd0 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b  um.** value of [
20be0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
20bf0 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65  sed()] since the
20c00 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
20c10 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73  .** was last res
20c20 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  et.  ^The values
20c30 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
20c40 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
20c50 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
20c60 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
20c70 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
20c80 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
20c90 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65   added by SQLite
20ca0 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e   in its implemen
20cb0 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  tation of [sqlit
20cc0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  e3_malloc()],.**
20cd0 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
20ce0 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
20cf0 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
20d00 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
20d10 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
20d20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
20d30 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a   may call..**.**
20d40 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67   ^The memory hig
20d50 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  h-water mark is 
20d60 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72  reset to the cur
20d70 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  rent value of.**
20d80 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
20d90 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20  _used()] if and 
20da0 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61  only if the para
20db0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
20dc0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
20dd0 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
20de0 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  .  ^The value re
20df0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71  turned.** by [sq
20e00 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
20e10 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68  hwater(1)] is th
20e20 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
20e30 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68  k.** prior to th
20e40 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69  e reset..*/.sqli
20e50 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
20e60 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
20e70 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  id);.sqlite3_int
20e80 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
20e90 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
20ea0 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
20eb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
20ec0 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
20ed0 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
20ee0 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
20ef0 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
20f00 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
20f10 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
20f20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
20f30 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
20f40 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
20f50 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
20f60 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
20f70 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
20f80 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
20f90 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
20fa0 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
20fb0 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
20fc0 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
20fd0 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
20fe0 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
20ff0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
21000 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
21010 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
21020 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
21030 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
21040 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
21050 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
21060 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
21070 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
21080 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
21090 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20  to buffer P..** 
210a0 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72  ^The P parameter
210b0 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70   can be a NULL p
210c0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ointer..**.** ^I
210d0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  f this routine h
210e0 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76  as not been prev
210f0 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72  iously called or
21100 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
21110 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c  .** call had N l
21120 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20  ess than one or 
21130 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
21140 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50  or P, then the P
21150 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64  RNG is.** seeded
21160 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
21170 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
21180 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
21190 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65  method of.** the
211a0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
211b0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
211c0 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f  * ^If the previo
211d0 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
211e0 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e  routine had an N
211f0 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e   of 1 or more an
21200 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20  d a.** non-NULL 
21210 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64  P then the pseud
21220 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
21230 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
21240 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
21250 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
21260 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
21270 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
21280 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64   method..*/.void
21290 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
212a0 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
212b0 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
212c0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
212d0 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
212e0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45   Callbacks.** ME
212f0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
21300 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 68   KEYWORDS: {auth
21310 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 7d  orizer callback}
21320 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
21330 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
21340 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  n authorizer cal
21350 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72  lback with a par
21360 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
21370 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
21380 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68  , supplied in th
21390 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
213a0 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72  ..** ^The author
213b0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
213c0 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
213d0 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
213e0 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
213f0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
21400 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
21410 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
21420 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
21430 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
21440 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69  are_v3()], [sqli
21450 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
21460 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
21470 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61  re16_v2()],.** a
21480 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
21490 61 72 65 31 36 5f 76 33 28 29 5d 2e 20 20 5e 41  are16_v3()].  ^A
214a0 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
214b0 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
214c0 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
214d0 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
214e0 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
214f0 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
21500 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
21510 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21520 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
21530 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
21540 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
21550 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75  llowed.  ^The au
21560 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
21570 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
21580 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
21590 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
215a0 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
215b0 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
215c0 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
215d0 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
215e0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
215f0 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
21600 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
21610 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
21620 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
21630 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
21640 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
21650 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
21660 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61  rror.  ^If the a
21670 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
21680 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
21690 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
216a0 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
216b0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
216c0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
216d0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
216e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
216f0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
21700 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
21710 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
21720 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
21730 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
21740 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
21750 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
21760 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
21770 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
21780 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
21790 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
217a0 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63  ok.  ^When the c
217b0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
217c0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
217d0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
217e0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
217f0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
21800 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
21810 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
21820 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
21830 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
21840 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
21850 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
21860 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  nied. .**.** ^Th
21870 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
21880 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
21890 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
218a0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
218b0 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
218c0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
218d0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
218e0 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65   interface. ^The
218f0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
21900 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
21910 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
21920 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
21930 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
21940 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
21950 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
21960 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
21970 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68  horized. ^The th
21980 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
21990 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
219a0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
219b0 61 72 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20  are either NULL 
219c0 70 6f 69 6e 74 65 72 73 20 6f 72 20 7a 65 72 6f  pointers or zero
219d0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
219e0 6e 67 73 0a 2a 2a 20 74 68 61 74 20 63 6f 6e 74  ngs.** that cont
219f0 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 64  ain additional d
21a00 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
21a10 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
21a20 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41 70 70  thorized..** App
21a30 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 61  lications must a
21a40 6c 77 61 79 73 20 62 65 20 70 72 65 70 61 72 65  lways be prepare
21a50 64 20 74 6f 20 65 6e 63 6f 75 6e 74 65 72 20 61  d to encounter a
21a60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e   NULL pointer in
21a70 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 74   any.** of the t
21a80 68 69 72 64 20 74 68 72 6f 75 67 68 20 74 68 65  hird through the
21a90 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
21aa0 73 20 6f 66 20 74 68 65 20 61 75 74 68 6f 72 69  s of the authori
21ab0 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e  zation callback.
21ac0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
21ad0 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
21ae0 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
21af0 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
21b00 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
21b10 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
21b20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
21b30 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
21b40 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
21b50 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
21b60 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
21b70 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
21b80 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
21b90 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
21ba0 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
21bb0 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
21bc0 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
21bd0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
21be0 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
21bf0 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
21c00 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
21c10 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
21c20 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
21c30 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20   of a table..** 
21c40 5e 57 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73  ^When a table is
21c50 20 72 65 66 65 72 65 6e 63 65 64 20 62 79 20 61   referenced by a
21c60 20 5b 53 45 4c 45 43 54 5d 20 62 75 74 20 6e 6f   [SELECT] but no
21c70 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61   column values a
21c80 72 65 0a 2a 2a 20 65 78 74 72 61 63 74 65 64 20  re.** extracted 
21c90 66 72 6f 6d 20 74 68 61 74 20 74 61 62 6c 65 20  from that table 
21ca0 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 69 6e 20  (for example in 
21cb0 61 20 71 75 65 72 79 20 6c 69 6b 65 0a 2a 2a 20  a query like.** 
21cc0 22 53 45 4c 45 43 54 20 63 6f 75 6e 74 28 2a 29  "SELECT count(*)
21cd0 20 46 52 4f 4d 20 74 61 62 22 29 20 74 68 65 6e   FROM tab") then
21ce0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 52 45 41   the [SQLITE_REA
21cf0 44 5d 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  D] authorizer ca
21d00 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 69 6e 76  llback.** is inv
21d10 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 74 68  oked once for th
21d20 61 74 20 74 61 62 6c 65 20 77 69 74 68 20 61 20  at table with a 
21d30 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20 74 68 61 74  column name that
21d40 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
21d50 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
21d60 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
21d70 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61  SQLITE_DELETE] a
21d80 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
21d90 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
21da0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
21db0 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65  the [DELETE] ope
21dc0 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20  ration proceeds 
21dd0 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e  but the.** [trun
21de0 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f  cate optimizatio
21df0 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61  n] is disabled a
21e00 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20  nd all rows are 
21e10 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75  deleted individu
21e20 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  ally..**.** An a
21e30 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65  uthorizer is use
21e40 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
21e50 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
21e60 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ing].** SQL stat
21e70 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75  ements from an u
21e80 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c  ntrusted source,
21e90 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20   to ensure that 
21ea0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
21eb0 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79  ts.** do not try
21ec0 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20   to access data 
21ed0 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c  they are not all
21ee0 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20  owed to see, or 
21ef0 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
21f00 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75  .** try to execu
21f10 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61  te malicious sta
21f20 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d  tements that dam
21f30 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  age the database
21f40 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
21f50 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
21f60 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73  n may allow a us
21f70 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69  er to enter arbi
21f80 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65  trary.** SQL que
21f90 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74  ries for evaluat
21fa0 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73  ion by a databas
21fb0 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c  e.  But the appl
21fc0 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20  ication does.** 
21fd0 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65  not want the use
21fe0 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20  r to be able to 
21ff0 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63  make arbitrary c
22000 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a  hanges to the.**
22010 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61   database.  An a
22020 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20  uthorizer could 
22030 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70  then be put in p
22040 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a  lace while the.*
22050 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  * user-entered S
22060 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c  QL is being [sql
22070 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
22080 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a  repared] that.**
22090 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79   disallows every
220a0 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45  thing except [SE
220b0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73  LECT] statements
220c0 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ..**.** Applicat
220d0 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74  ions that need t
220e0 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72  o process SQL fr
220f0 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  om untrusted sou
22100 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c  rces.** might al
22110 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65  so consider lowe
22120 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69  ring resource li
22130 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69  mits using [sqli
22140 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
22150 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74  and limiting dat
22160 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67  abase size using
22170 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63   the [max_page_c
22180 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a  ount] [PRAGMA].*
22190 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  * in addition to
221a0 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72   using an author
221b0 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  izer..**.** ^(On
221c0 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68  ly a single auth
221d0 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e  orizer can be in
221e0 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61   place on a data
221f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
22200 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45  ** at a time.  E
22210 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
22220 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
22230 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  er overrides the
22240 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c  .** previous cal
22250 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74  l.)^  ^Disable t
22260 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79  he authorizer by
22270 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55   installing a NU
22280 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  LL callback..** 
22290 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69  The authorizer i
222a0 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
222b0 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fault..**.** The
222c0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
222d0 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
222e0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
222f0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
22300 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
22310 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
22320 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ed the authorize
22330 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e  r callback..** N
22340 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
22350 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
22360 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
22370 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
22380 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
22390 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
223a0 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
223b0 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
223c0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
223d0 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74  .** ^When [sqlit
223e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
223f0 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70   is used to prep
22400 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  are a statement,
22410 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
22420 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72  t might be re-pr
22430 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73  epared during [s
22440 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64  qlite3_step()] d
22450 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65  ue to a .** sche
22460 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63  ma change.  Henc
22470 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  e, the applicati
22480 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65  on should ensure
22490 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72   that the.** cor
224a0 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20  rect authorizer 
224b0 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73  callback remains
224c0 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67   in place during
224d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
224e0 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f  ep()]..**.** ^No
224f0 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68  te that the auth
22500 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
22510 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20  is invoked only 
22520 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  during.** [sqlit
22530 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
22540 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20   its variants.  
22550 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73  Authorization is
22560 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65   not.** performe
22570 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65  d during stateme
22580 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e  nt evaluation in
22590 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
225a0 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20  ], unless.** as 
225b0 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72  stated in the pr
225c0 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
225d0 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
225e0 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69   invokes.** sqli
225f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
22600 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20   to reprepare a 
22610 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
22620 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  a schema change.
22630 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
22640 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
22650 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
22660 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
22670 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
22680 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
22690 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
226a0 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
226b0 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
226c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
226d0 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
226e0 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
226f0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
22700 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
22710 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  zer callback fun
22720 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72  ction] must.** r
22730 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51  eturn either [SQ
22740 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20  LITE_OK] or one 
22750 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e  of these two con
22760 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a  stants in order.
22770 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c  ** to signal SQL
22780 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e  ite whether or n
22790 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  ot the action is
227a0 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65   permitted.  See
227b0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
227c0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
227d0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63  | authorizer doc
227e0 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
227f0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
22800 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
22810 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54   Note that SQLIT
22820 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f  E_IGNORE is also
22830 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66   used as a [conf
22840 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  lict resolution 
22850 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65  mode].** returne
22860 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  d from the [sqli
22870 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66  te3_vtab_on_conf
22880 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63  lict()] interfac
22890 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
228a0 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
228b0 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
228c0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
228d0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
228e0 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
228f0 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
22900 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
22910 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
22920 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
22930 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
22940 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
22950 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
22960 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
22970 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
22980 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
22990 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
229a0 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
229b0 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
229c0 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
229d0 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
229e0 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
229f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
22a00 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
22a10 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
22a20 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
22a30 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
22a40 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
22a50 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
22a60 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
22a70 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
22a80 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
22a90 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
22aa0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
22ab0 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
22ac0 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
22ad0 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
22ae0 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
22af0 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
22b00 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
22b10 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
22b20 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
22b30 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
22b40 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
22b50 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
22b60 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
22b70 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
22b80 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
22b90 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
22ba0 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d   ^(The 5th param
22bb0 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
22bc0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
22bd0 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
22be0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
22bf0 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
22c00 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
22c10 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20  icable.)^  ^The 
22c20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
22c30 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
22c40 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
22c50 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
22c60 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
22c70 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
22c80 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
22c90 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
22ca0 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
22cb0 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
22cc0 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
22cd0 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
22ce0 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
22cf0 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
22d00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22d10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
22d20 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
22d30 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
22d40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22d50 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
22d60 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
22d70 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
22d80 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
22d90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
22da0 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
22db0 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
22dc0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
22dd0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22de0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
22df0 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
22e00 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
22e10 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
22e20 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
22e30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
22e40 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
22e50 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
22e60 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
22e70 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22e80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
22e90 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
22ea0 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
22eb0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
22ec0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
22ed0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
22ee0 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
22ef0 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
22f00 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
22f10 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22f20 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
22f30 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
22f40 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
22f50 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
22f60 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
22f70 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
22f80 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
22f90 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
22fa0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22fb0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22fc0 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
22fd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
22fe0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22ff0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
23000 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23010 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
23020 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
23030 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
23040 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
23050 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23060 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
23070 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
23080 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
23090 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
230a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
230b0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
230c0 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
230d0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
230e0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
230f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23100 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
23110 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
23120 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
23130 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
23140 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23150 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
23160 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
23170 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
23180 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
23190 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
231a0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
231b0 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
231c0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
231d0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
231e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
231f0 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
23200 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
23210 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
23220 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
23230 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23240 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
23250 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
23260 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
23270 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
23280 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
23290 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
232a0 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
232b0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
232c0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
232d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
232e0 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
232f0 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
23300 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
23310 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
23320 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
23330 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
23340 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
23350 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
23360 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
23370 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
23380 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
23390 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
233a0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
233b0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
233c0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
233d0 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
233e0 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  22   /* Operatio
233f0 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  n       NULL    
23400 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
23410 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
23420 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
23430 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
23440 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
23450 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
23460 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
23470 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
23480 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
23490 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
234a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
234b0 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
234c0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
234d0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
234e0 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
234f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23500 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
23510 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
23520 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
23530 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
23540 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23550 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
23560 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
23570 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
23580 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
23590 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
235a0 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
235b0 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
235c0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
235d0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
235e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
235f0 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
23600 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
23610 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
23620 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
23630 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23640 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
23650 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
23660 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
23670 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
23680 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23690 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
236a0 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e         31   /* N
236b0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46  ULL            F
236c0 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a  unction Name   *
236d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
236e0 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20  _SAVEPOINT      
236f0 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70        32   /* Op
23700 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61  eration       Sa
23710 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f  vepoint Name  */
23720 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23730 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
23740 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
23750 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23  longer used */.#
23760 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
23770 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20  CURSIVE         
23780 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20     33   /* NULL 
23790 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
237a0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f             */../
237b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
237c0 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69  racing And Profi
237d0 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ling Functions.*
237e0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
237f0 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  3.**.** These ro
23800 75 74 69 6e 65 73 20 61 72 65 20 64 65 70 72 65  utines are depre
23810 63 61 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b  cated. Use the [
23820 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
23830 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
23840 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
23850 72 6f 75 74 69 6e 65 73 20 64 65 73 63 72 69 62  routines describ
23860 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54  ed here..**.** T
23870 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
23880 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
23890 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
238a0 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
238b0 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
238c0 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
238d0 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
238e0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
238f0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
23900 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
23910 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
23920 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
23930 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
23940 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
23950 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
23960 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
23970 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
23980 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
23990 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
239a0 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
239b0 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
239c0 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
239d0 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
239e0 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
239f0 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
23a00 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
23a10 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
23a20 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
23a30 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
23a40 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
23a50 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
23a60 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
23a70 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
23a80 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
23a90 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
23aa0 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
23ab0 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
23ac0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
23ad0 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d  E_TRACE_SIZE_LIM
23ae0 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  IT] compile-time
23af0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
23b00 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20  sed to limit.** 
23b10 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62  the length of [b
23b20 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20  ound parameter] 
23b30 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65  expansion in the
23b40 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74   output of sqlit
23b50 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a  e3_trace()..**.*
23b60 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
23b70 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
23b80 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
23b90 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f  rofile() is invo
23ba0 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53  ked.** as each S
23bb0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  QL statement fin
23bc0 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f  ishes.  ^The pro
23bd0 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f  file callback co
23be0 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72  ntains.** the or
23bf0 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
23c00 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74   text and an est
23c10 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c  imate of wall-cl
23c20 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68  ock time.** of h
23c30 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
23c40 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
23c50 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  un.  ^The profil
23c60 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69  e callback.** ti
23c70 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f  me is in units o
23c80 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68  f nanoseconds, h
23c90 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65  owever the curre
23ca0 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
23cb0 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70  n.** is only cap
23cc0 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63  able of millisec
23cd0 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73  ond resolution s
23ce0 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20  o the six least 
23cf0 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64  significant.** d
23d00 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d  igits in the tim
23d10 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73  e are meaningles
23d20 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  s.  Future versi
23d30 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ons of SQLite.**
23d40 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67   might provide g
23d50 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f  reater resolutio
23d60 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65  n on the profile
23d70 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65  r callback.  The
23d80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66  .** sqlite3_prof
23d90 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ile() function i
23da0 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70  s considered exp
23db0 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
23dc0 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63  .** subject to c
23dd0 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
23de0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
23df0 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45  te..*/.SQLITE_DE
23e00 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73  PRECATED void *s
23e10 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
23e20 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
23e30 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
23e40 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
23e50 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
23e60 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69  CATED void *sqli
23e70 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
23e80 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
23e90 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
23ea0 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
23eb0 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
23ec0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
23ed0 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 45  REF: SQL Trace E
23ee0 76 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  vent Codes.** KE
23ef0 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
23f00 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  RACE.**.** These
23f10 20 63 6f 6e 73 74 61 6e 74 73 20 69 64 65 6e 74   constants ident
23f20 69 66 79 20 63 6c 61 73 73 65 73 20 6f 66 20 65  ify classes of e
23f30 76 65 6e 74 73 20 74 68 61 74 20 63 61 6e 20 62  vents that can b
23f40 65 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75  e monitored.** u
23f50 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  sing the [sqlite
23f60 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 74 72  3_trace_v2()] tr
23f70 61 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68  acing logic.  Th
23f80 65 20 4d 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  e M argument.** 
23f90 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  to [sqlite3_trac
23fa0 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 5d 20 69  e_v2(D,M,X,P)] i
23fb0 73 20 61 6e 20 4f 52 2d 65 64 20 63 6f 6d 62 69  s an OR-ed combi
23fc0 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72  nation of one or
23fd0 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74 68 65 20   more of.** the 
23fe0 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61  following consta
23ff0 6e 74 73 2e 20 20 5e 54 68 65 20 66 69 72 73 74  nts.  ^The first
24000 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
24010 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a   trace callback.
24020 2a 2a 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  ** is one of the
24030 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74   following const
24040 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  ants..**.** New 
24050 74 72 61 63 69 6e 67 20 63 6f 6e 73 74 61 6e 74  tracing constant
24060 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
24070 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
24080 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63  s..**.** ^A trac
24090 65 20 63 61 6c 6c 62 61 63 6b 20 68 61 73 20 66  e callback has f
240a0 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 78  our arguments: x
240b0 43 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58  Callback(T,C,P,X
240c0 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67  )..** ^The T arg
240d0 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
240e0 74 68 65 20 69 6e 74 65 67 65 72 20 74 79 70 65  the integer type
240f0 20 63 6f 64 65 73 20 61 62 6f 76 65 2e 0a 2a 2a   codes above..**
24100 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74   ^The C argument
24110 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
24120 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65  e context pointe
24130 72 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  r passed in as t
24140 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72 67  he.** fourth arg
24150 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
24160 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 2e 0a 2a  3_trace_v2()]..*
24170 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72  * The P and X ar
24180 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e  guments are poin
24190 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69  ters whose meani
241a0 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e  ngs depend on T.
241b0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
241c0 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54  [SQLITE_TRACE_ST
241d0 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  MT]] <dt>SQLITE_
241e0 54 52 41 43 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a  TRACE_STMT</dt>.
241f0 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54  ** <dd>^An SQLIT
24200 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 63 61 6c  E_TRACE_STMT cal
24210 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
24220 20 77 68 65 6e 20 61 20 70 72 65 70 61 72 65 64   when a prepared
24230 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 66 69   statement.** fi
24240 72 73 74 20 62 65 67 69 6e 73 20 72 75 6e 6e 69  rst begins runni
24250 6e 67 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20  ng and possibly 
24260 61 74 20 6f 74 68 65 72 20 74 69 6d 65 73 20 64  at other times d
24270 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 65 78 65  uring the.** exe
24280 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 70 72  cution of the pr
24290 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
242a0 2c 20 73 75 63 68 20 61 73 20 61 74 20 74 68 65  , such as at the
242b0 20 73 74 61 72 74 20 6f 66 20 65 61 63 68 0a 2a   start of each.*
242c0 2a 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f  * trigger subpro
242d0 67 72 61 6d 2e 20 5e 54 68 65 20 50 20 61 72 67  gram. ^The P arg
242e0 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
242f0 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 70 72  er to the.** [pr
24300 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24310 5d 2e 20 5e 54 68 65 20 58 20 61 72 67 75 6d 65  ]. ^The X argume
24320 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
24330 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  to a string whic
24340 68 0a 2a 2a 20 69 73 20 74 68 65 20 75 6e 65 78  h.** is the unex
24350 70 61 6e 64 65 64 20 53 51 4c 20 74 65 78 74 20  panded SQL text 
24360 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20  of the prepared 
24370 73 74 61 74 65 6d 65 6e 74 20 6f 72 20 61 6e 20  statement or an 
24380 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20  SQL comment .** 
24390 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74  that indicates t
243a0 68 65 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  he invocation of
243b0 20 61 20 74 72 69 67 67 65 72 2e 20 20 5e 54 68   a trigger.  ^Th
243c0 65 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20 63  e callback can c
243d0 6f 6d 70 75 74 65 0a 2a 2a 20 74 68 65 20 73 61  ompute.** the sa
243e0 6d 65 20 74 65 78 74 20 74 68 61 74 20 77 6f 75  me text that wou
243f0 6c 64 20 68 61 76 65 20 62 65 65 6e 20 72 65 74  ld have been ret
24400 75 72 6e 65 64 20 62 79 20 74 68 65 20 6c 65 67  urned by the leg
24410 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61  acy [sqlite3_tra
24420 63 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ce()].** interfa
24430 63 65 20 62 79 20 75 73 69 6e 67 20 74 68 65 20  ce by using the 
24440 58 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20  X argument when 
24450 58 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 2d  X begins with "-
24460 2d 22 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a  -" and invoking.
24470 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 70 61  ** [sqlite3_expa
24480 6e 64 65 64 5f 73 71 6c 28 50 29 5d 20 6f 74 68  nded_sql(P)] oth
24490 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  erwise..**.** [[
244a0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f  SQLITE_TRACE_PRO
244b0 46 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  FILE]] <dt>SQLIT
244c0 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 3c  E_TRACE_PROFILE<
244d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20  /dt>.** <dd>^An 
244e0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f  SQLITE_TRACE_PRO
244f0 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 70 72  FILE callback pr
24500 6f 76 69 64 65 73 20 61 70 70 72 6f 78 69 6d 61  ovides approxima
24510 74 65 6c 79 20 74 68 65 20 73 61 6d 65 0a 2a 2a  tely the same.**
24520 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
24530 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
24540 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66  he [sqlite3_prof
24550 69 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63 6b 2e  ile()] callback.
24560 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d  .** ^The P argum
24570 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
24580 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
24590 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
245a0 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65   the.** X argume
245b0 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 36  nt points to a 6
245c0 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 77 68  4-bit integer wh
245d0 69 63 68 20 69 73 20 74 68 65 20 65 73 74 69 6d  ich is the estim
245e0 61 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65 20 6e  ated of.** the n
245f0 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63  umber of nanosec
24600 6f 6e 64 20 74 68 61 74 20 74 68 65 20 70 72 65  ond that the pre
24610 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
24620 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20  took to run..** 
24630 5e 54 68 65 20 53 51 4c 49 54 45 5f 54 52 41 43  ^The SQLITE_TRAC
24640 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61  E_PROFILE callba
24650 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  ck is invoked wh
24660 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
24670 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a   finishes..**.**
24680 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f   [[SQLITE_TRACE_
24690 52 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  ROW]] <dt>SQLITE
246a0 5f 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a  _TRACE_ROW</dt>.
246b0 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54  ** <dd>^An SQLIT
246c0 45 5f 54 52 41 43 45 5f 52 4f 57 20 63 61 6c 6c  E_TRACE_ROW call
246d0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
246e0 77 68 65 6e 65 76 65 72 20 61 20 70 72 65 70 61  whenever a prepa
246f0 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
24700 20 67 65 6e 65 72 61 74 65 73 20 61 20 73 69 6e   generates a sin
24710 67 6c 65 20 72 6f 77 20 6f 66 20 72 65 73 75 6c  gle row of resul
24720 74 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50 20 61  t.  .** ^The P a
24730 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
24740 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65  nter to the [pre
24750 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24760 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72   and the.** X ar
24770 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64  gument is unused
24780 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
24790 5f 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c  _TRACE_CLOSE]] <
247a0 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  dt>SQLITE_TRACE_
247b0 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CLOSE</dt>.** <d
247c0 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41  d>^An SQLITE_TRA
247d0 43 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62 61 63  CE_CLOSE callbac
247e0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
247f0 6e 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  n a database.** 
24800 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
24810 73 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67  s..** ^The P arg
24820 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
24830 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  er to the [datab
24840 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
24850 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 74 68  object.** and th
24860 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e X argument is 
24870 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e  unused..** </dl>
24880 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
24890 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 20 20  TE_TRACE_STMT   
248a0 20 20 20 20 30 78 30 31 0a 23 64 65 66 69 6e 65      0x01.#define
248b0 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52   SQLITE_TRACE_PR
248c0 4f 46 49 4c 45 20 20 20 20 30 78 30 32 0a 23 64  OFILE    0x02.#d
248d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
248e0 43 45 5f 52 4f 57 20 20 20 20 20 20 20 20 30 78  CE_ROW        0x
248f0 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
24900 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 20 20  E_TRACE_CLOSE   
24910 20 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43     0x08../*.** C
24920 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61  API3REF: SQL Tra
24930 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f  ce Hook.** METHO
24940 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
24950 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72   ^The sqlite3_tr
24960 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 20  ace_v2(D,M,X,P) 
24970 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
24980 65 72 73 20 61 20 74 72 61 63 65 20 63 61 6c 6c  ers a trace call
24990 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
249a0 20 58 20 61 67 61 69 6e 73 74 20 5b 64 61 74 61   X against [data
249b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
249c0 20 44 2c 20 75 73 69 6e 67 20 70 72 6f 70 65 72   D, using proper
249d0 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64  ty mask M.** and
249e0 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72   context pointer
249f0 20 50 2e 20 20 5e 49 66 20 74 68 65 20 58 20 63   P.  ^If the X c
24a00 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 4e 55  allback is.** NU
24a10 4c 4c 20 6f 72 20 69 66 20 74 68 65 20 4d 20 6d  LL or if the M m
24a20 61 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74 68 65  ask is zero, the
24a30 6e 20 74 72 61 63 69 6e 67 20 69 73 20 64 69 73  n tracing is dis
24a40 61 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 4d  abled.  The.** M
24a50 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
24a60 20 62 65 20 74 68 65 20 62 69 74 77 69 73 65 20   be the bitwise 
24a70 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f  OR-ed combinatio
24a80 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20  n of.** zero or 
24a90 6d 6f 72 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  more [SQLITE_TRA
24aa0 43 45 5d 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a  CE] constants..*
24ab0 2a 0a 2a 2a 20 5e 45 61 63 68 20 63 61 6c 6c 20  *.** ^Each call 
24ac0 74 6f 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  to either sqlite
24ad0 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c  3_trace() or sql
24ae0 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20  ite3_trace_v2() 
24af0 6f 76 65 72 72 69 64 65 73 20 0a 2a 2a 20 28 63  overrides .** (c
24b00 61 6e 63 65 6c 73 29 20 61 6e 79 20 70 72 69 6f  ancels) any prio
24b10 72 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  r calls to sqlit
24b20 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71  e3_trace() or sq
24b30 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
24b40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58 20 63  ..**.** ^The X c
24b50 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
24b60 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 79 20  ed whenever any 
24b70 6f 66 20 74 68 65 20 65 76 65 6e 74 73 20 69 64  of the events id
24b80 65 6e 74 69 66 69 65 64 20 62 79 20 0a 2a 2a 20  entified by .** 
24b90 6d 61 73 6b 20 4d 20 6f 63 63 75 72 2e 20 20 5e  mask M occur.  ^
24ba0 54 68 65 20 69 6e 74 65 67 65 72 20 72 65 74 75  The integer retu
24bb0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 74 68  rn value from th
24bc0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 75  e callback is cu
24bd0 72 72 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72  rrently.** ignor
24be0 65 64 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20  ed, though this 
24bf0 6d 61 79 20 63 68 61 6e 67 65 20 69 6e 20 66 75  may change in fu
24c00 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 20 20  ture releases.  
24c10 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c  Callback.** impl
24c20 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
24c30 6c 64 20 72 65 74 75 72 6e 20 7a 65 72 6f 20 74  ld return zero t
24c40 6f 20 65 6e 73 75 72 65 20 66 75 74 75 72 65 20  o ensure future 
24c50 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
24c60 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61  *.** ^A trace ca
24c70 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
24c80 64 20 77 69 74 68 20 66 6f 75 72 20 61 72 67 75  d with four argu
24c90 6d 65 6e 74 73 3a 20 63 61 6c 6c 62 61 63 6b 28  ments: callback(
24ca0 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68  T,C,P,X)..** ^Th
24cb0 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e T argument is 
24cc0 6f 6e 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  one of the [SQLI
24cd0 54 45 5f 54 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e  TE_TRACE].** con
24ce0 73 74 61 6e 74 73 20 74 6f 20 69 6e 64 69 63 61  stants to indica
24cf0 74 65 20 77 68 79 20 74 68 65 20 63 61 6c 6c 62  te why the callb
24d00 61 63 6b 20 77 61 73 20 69 6e 76 6f 6b 65 64 2e  ack was invoked.
24d10 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d  .** ^The C argum
24d20 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ent is a copy of
24d30 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69   the context poi
24d40 6e 74 65 72 2e 0a 2a 2a 20 54 68 65 20 50 20 61  nter..** The P a
24d50 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61  nd X arguments a
24d60 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73  re pointers whos
24d70 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e  e meanings depen
24d80 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68  d on T..**.** Th
24d90 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f  e sqlite3_trace_
24da0 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  v2() interface i
24db0 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 72 65  s intended to re
24dc0 70 6c 61 63 65 20 74 68 65 20 6c 65 67 61 63 79  place the legacy
24dd0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
24de0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d  sqlite3_trace()]
24df0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
24e00 6f 66 69 6c 65 28 29 5d 2c 20 62 6f 74 68 20 6f  ofile()], both o
24e10 66 20 77 68 69 63 68 0a 2a 2a 20 61 72 65 20 64  f which.** are d
24e20 65 70 72 65 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e  eprecated..*/.in
24e30 74 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f  t sqlite3_trace_
24e40 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  v2(.  sqlite3*,.
24e50 20 20 75 6e 73 69 67 6e 65 64 20 75 4d 61 73 6b    unsigned uMask
24e60 2c 0a 20 20 69 6e 74 28 2a 78 43 61 6c 6c 62 61  ,.  int(*xCallba
24e70 63 6b 29 28 75 6e 73 69 67 6e 65 64 2c 76 6f 69  ck)(unsigned,voi
24e80 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c  d*,void*,void*),
24e90 0a 20 20 76 6f 69 64 20 2a 70 43 74 78 0a 29 3b  .  void *pCtx.);
24ea0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24eb0 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73  : Query Progress
24ec0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45   Callbacks.** ME
24ed0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
24ee0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
24ef0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
24f00 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72  r(D,N,X,P) inter
24f10 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20  face causes the 
24f20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
24f30 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76  tion X to be inv
24f40 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
24f50 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75  y during long ru
24f60 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a  nning calls to.*
24f70 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
24f80 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
24f90 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  p()] and [sqlite
24fa0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66  3_get_table()] f
24fb0 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  or.** database c
24fc0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e  onnection D.  An
24fd0 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72   example use for
24fe0 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61   this.** interfa
24ff0 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20  ce is to keep a 
25000 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69  GUI updated duri
25010 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79  ng a large query
25020 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72  ..**.** ^The par
25030 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73  ameter P is pass
25040 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
25050 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
25060 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c   to the .** call
25070 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e  back function X.
25080 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
25090 20 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78   N is the approx
250a0 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20  imate number of 
250b0 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63  .** [virtual mac
250c0 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e  hine instruction
250d0 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c  s] that are eval
250e0 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75  uated between su
250f0 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f  ccessive.** invo
25100 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63  cations of the c
25110 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20  allback X.  ^If 
25120 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f  N is less than o
25130 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67  ne then the prog
25140 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  ress.** handler 
25150 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  is disabled..**.
25160 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  ** ^Only a singl
25170 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
25180 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65  er may be define
25190 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65  d at one time pe
251a0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
251b0 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74  onnection]; sett
251c0 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65  ing a new progre
251d0 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65  ss handler cance
251e0 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e  ls the.** old on
251f0 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72  e.  ^Setting par
25200 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c  ameter X to NULL
25210 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72   disables the pr
25220 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
25230 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73  ** ^The progress
25240 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f   handler is also
25250 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74   disabled by set
25260 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75  ting N to a valu
25270 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31  e less.** than 1
25280 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
25290 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
252a0 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
252b0 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ro, the operatio
252c0 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
252d0 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
252e0 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
252f0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
25300 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
25310 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65   on a GUI progre
25320 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a  ss dialog box..*
25330 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73  *.** The progres
25340 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  s handler callba
25350 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
25360 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
25370 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
25380 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25390 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
253a0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
253b0 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74  ndler..** Note t
253c0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
253d0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
253e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
253f0 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
25400 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
25410 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
25420 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
25430 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
25440 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76  ragraph..**.*/.v
25450 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  oid sqlite3_prog
25460 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c  ress_handler(sql
25470 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28  ite3*, int, int(
25480 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
25490 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
254a0 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65  EF: Opening A Ne
254b0 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  w Database Conne
254c0 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55  ction.** CONSTRU
254d0 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  CTOR: sqlite3.**
254e0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
254f0 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69  nes open an SQLi
25500 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  te database file
25510 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79   as specified by
25520 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d   the .** filenam
25530 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65  e argument. ^The
25540 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
25550 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
25560 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
25570 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
25580 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
25590 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
255a0 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
255b0 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
255c0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
255d0 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61  n16(). ^(A [data
255e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
255f0 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c   handle is usual
25600 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ly.** returned i
25610 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66  n *ppDb, even if
25620 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
25630 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65  .  The only exce
25640 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a  ption is that.**
25650 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e   if SQLite is un
25660 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
25670 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
25680 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
25690 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20  ject,.** a NULL 
256a0 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20  will be written 
256b0 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65  into *ppDb inste
256c0 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20  ad of a pointer 
256d0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  to the [sqlite3]
256e0 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28  .** object.)^ ^(
256f0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
25700 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f  is opened (and/o
25710 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65  r created) succe
25720 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a  ssfully, then.**
25730 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
25740 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
25750 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
25760 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
25770 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c  .)^ ^The.** [sql
25780 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
25790 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
257a0 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
257b0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
257c0 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
257d0 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
257e0 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
257f0 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20  error following 
25800 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79  a failure of any
25810 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
25820 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e  e3_open() routin
25830 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  es..**.** ^The d
25840 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
25850 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f  will be UTF-8 fo
25860 72 20 64 61 74 61 62 61 73 65 73 20 63 72 65 61  r databases crea
25870 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c  ted using.** sql
25880 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
25890 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
258a0 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  .  ^The default 
258b0 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74  encoding for dat
258c0 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65  abases.** create
258d0 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  d using sqlite3_
258e0 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65  open16() will be
258f0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
25900 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
25910 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
25920 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
25930 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
25940 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
25950 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
25960 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
25970 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
25980 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
25990 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a  e released by.**
259a0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
259b0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
259c0 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
259d0 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
259e0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
259f0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65  3_open_v2() inte
25a00 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
25a10 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a   sqlite3_open().
25a20 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
25a30 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64  t accepts two ad
25a40 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
25a50 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
25a60 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76  al control.** ov
25a70 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  er the new datab
25a80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
25a90 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72   ^(The flags par
25aa0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c  ameter to.** sql
25ab0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63  ite3_open_v2() c
25ac0 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a  an take one of.*
25ad0 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
25ae0 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70  three values, op
25af0 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
25b00 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  d with the .** [
25b10 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
25b20 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
25b30 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b  EN_FULLMUTEX], [
25b40 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
25b50 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51  EDCACHE],.** [SQ
25b60 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
25b70 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20  ECACHE], and/or 
25b80 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
25b90 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a  ] flags:)^.**.**
25ba0 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b   <dl>.** ^(<dt>[
25bb0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
25bc0 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ONLY]</dt>.** <d
25bd0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
25be0 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64  s opened in read
25bf0 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20  -only mode.  If 
25c00 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
25c10 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79  s not.** already
25c20 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
25c30 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
25c40 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
25c50 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
25c60 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  ADWRITE]</dt>.**
25c70 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
25c80 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
25c90 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
25ca0 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c  ing if possible,
25cb0 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f   or reading.** o
25cc0 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20  nly if the file 
25cd0 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
25ce0 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
25cf0 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20  ing system.  In 
25d00 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74  either.** case t
25d10 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74  he database must
25d20 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
25d30 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  otherwise an err
25d40 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
25d50 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
25d60 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
25d70 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
25d80 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
25d90 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
25da0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
25db0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
25dc0 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e   and writing, an
25dd0 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a  d is created if.
25de0 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61  ** it does not a
25df0 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68  lready exist. Th
25e00 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69  is is the behavi
25e10 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79  or that is alway
25e20 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71  s used for.** sq
25e30 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
25e40 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
25e50 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  ).</dd>)^.** </d
25e60 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
25e70 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
25e80 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
25e90 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
25ea0 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
25eb0 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
25ec0 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
25ed0 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a  ined with other.
25ee0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
25ef0 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54  READONLY | SQLIT
25f00 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a  E_OPEN_* bits].*
25f10 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
25f20 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
25f30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
25f40 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
25f50 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
25f60 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
25f70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
25f80 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
25f90 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
25fa0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
25fb0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
25fc0 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
25fd0 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
25fe0 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
25ff0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
26000 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  e.  ^If the.** [
26010 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
26020 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
26030 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
26040 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
26050 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
26060 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
26070 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
26080 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
26090 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
260a0 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
260b0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
260c0 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54  tart-time..** ^T
260d0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
260e0 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61  SHAREDCACHE] fla
260f0 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
26100 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
26110 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62   to be.** eligib
26120 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65  le to use [share
26130 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72  d cache mode], r
26140 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
26150 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
26160 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
26170 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
26180 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
26190 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e  red_cache()].  ^
261a0 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  The.** [SQLITE_O
261b0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
261c0 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
261d0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
261e0 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20  ction to not.** 
261f0 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b  participate in [
26200 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
26210 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  e] even if it is
26220 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
26230 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
26240 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
26250 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68  _open_v2() is th
26260 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
26270 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
26280 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
26290 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
262a0 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
262b0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65  e that.** the ne
262c0 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
262d0 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ction should use
262e0 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  .  ^If the fourt
262f0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
26300 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
26310 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
26320 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
26330 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a  object is used..
26340 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
26350 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
26360 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69  ry:", then a pri
26370 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20  vate, temporary 
26380 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
26390 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64  se.** is created
263a0 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
263b0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d  ion.  ^This in-m
263c0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
263d0 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
263e0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
263f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
26400 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
26410 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
26420 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
26430 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
26440 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
26450 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
26460 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
26470 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
26480 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
26490 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
264a0 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
264b0 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
264c0 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
264d0 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
264e0 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
264f0 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
26500 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
26510 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
26520 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iguity..**.** ^I
26530 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
26540 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
26550 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
26560 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20  e, temporary.** 
26570 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65  on-disk database
26580 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64   will be created
26590 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65  .  ^This private
265a0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
265b0 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
265c0 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f  ly deleted as so
265d0 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61  on as the databa
265e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
265f0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   closed..**.** [
26600 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69  [URI filenames i
26610 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  n sqlite3_open()
26620 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e  ]] <h3>URI Filen
26630 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ames</h3>.**.** 
26640 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ^If [URI filenam
26650 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  e] interpretatio
26660 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e  n is enabled, an
26670 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  d the filename a
26680 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e  rgument.** begin
26690 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20  s with "file:", 
266a0 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d  then the filenam
266b0 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  e is interpreted
266c0 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a   as a URI. ^URI.
266d0 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  ** filename inte
266e0 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
266f0 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51  abled if the [SQ
26700 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
26710 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e  lag is.** set in
26720 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
26730 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ent to sqlite3_o
26740 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20  pen_v2(), or if 
26750 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65  it has.** been e
26760 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20  nabled globally 
26770 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
26780 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70  E_CONFIG_URI] op
26790 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a  tion with the.**
267a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
267b0 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79  ()] method or by
267c0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
267d0 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  _URI] compile-ti
267e0 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 55 52  me option..** UR
267f0 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  I filename inter
26800 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72  pretation is tur
26810 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65  ned off.** by de
26820 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72  fault, but futur
26830 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
26840 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c  Lite might enabl
26850 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a  e URI filename.*
26860 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  * interpretation
26870 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65   by default.  Se
26880 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  e "[URI filename
26890 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  s]" for addition
268a0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
268b0 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c  n..**.** URI fil
268c0 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65  enames are parse
268d0 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52  d according to R
268e0 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65  FC 3986. ^If the
268f0 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e   URI contains an
26900 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74  .** authority, t
26910 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65  hen it must be e
26920 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73  ither an empty s
26930 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72  tring or the str
26940 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f  ing .** "localho
26950 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74  st". ^If the aut
26960 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e  hority is not an
26970 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
26980 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e   "localhost", an
26990 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65   .** error is re
269a0 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61  turned to the ca
269b0 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d  ller. ^The fragm
269c0 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ent component of
269d0 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70   a URI, if .** p
269e0 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72  resent, is ignor
269f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ed..**.** ^SQLit
26a00 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20  e uses the path 
26a10 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65  component of the
26a20 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65   URI as the name
26a30 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c   of the disk fil
26a40 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61  e.** which conta
26a50 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ins the database
26a60 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62  . ^If the path b
26a70 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27  egins with a '/'
26a80 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20   character, .** 
26a90 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72  then it is inter
26aa0 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73  preted as an abs
26ab0 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20  olute path. ^If 
26ac0 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f  the path does no
26ad0 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68  t begin .** with
26ae0 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20   a '/' (meaning 
26af0 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
26b00 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d  ty section is om
26b10 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55  itted from the U
26b20 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  RI).** then the 
26b30 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65  path is interpre
26b40 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76  ted as a relativ
26b50 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e  e path. .** ^(On
26b60 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69   windows, the fi
26b70 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  rst component of
26b80 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
26b90 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65  h .** is a drive
26ba0 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28   specification (
26bb0 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a  e.g. "C:").)^.**
26bc0 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71  .** [[core URI q
26bd0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d  uery parameters]
26be0 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63  ].** The query c
26bf0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
26c00 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61  I may contain pa
26c10 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72  rameters that ar
26c20 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a  e interpreted.**
26c30 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74   either by SQLit
26c40 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20  e itself, or by 
26c50 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20  a [VFS | custom 
26c60 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
26c70 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61  on]..** SQLite a
26c80 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20  nd its built-in 
26c90 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65  [VFSes] interpre
26ca0 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  t the.** followi
26cb0 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ng query paramet
26cc0 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ers:.**.** <ul>.
26cd0 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73  **   <li> <b>vfs
26ce0 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22  </b>: ^The "vfs"
26cf0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
26d00 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66  e used to specif
26d10 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a  y the name of.**
26d20 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63       a VFS objec
26d30 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20  t that provides 
26d40 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
26d50 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
26d60 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20  hat should.**   
26d70 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63    be used to acc
26d80 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
26d90 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e   file on disk. ^
26da0 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  If this option i
26db0 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20  s set to.**     
26dc0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
26dd0 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
26de0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20  object is used. 
26df0 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
26e00 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46  nknown.**     VF
26e10 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e  S is an error. ^
26e20 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
26e30 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
26e40 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20   the vfs option 
26e50 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e  is.**     presen
26e60 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20  t, then the VFS 
26e70 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
26e80 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72   option takes pr
26e90 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a  ecedence over.**
26ea0 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70       the value p
26eb0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75  assed as the fou
26ec0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
26ed0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
26ee0 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
26ef0 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28   <b>mode</b>: ^(
26f00 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  The mode paramet
26f10 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
26f20 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72   either "ro", "r
26f30 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22  w",.**     "rwc"
26f40 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41  , or "memory". A
26f50 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74  ttempting to set
26f60 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72   it to any other
26f70 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20   value is.**    
26f80 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a   an error)^. .**
26f90 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73       ^If "ro" is
26fa0 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e   specified, then
26fb0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
26fc0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
26fd0 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63  -only .**     ac
26fe0 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66  cess, just as if
26ff0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
27000 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67  N_READONLY] flag
27010 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e   had been set in
27020 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69   the .**     thi
27030 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
27040 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
27050 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f  . ^If the mode o
27060 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20  ption is set to 
27070 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68  .**     "rw", th
27080 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
27090 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
270a0 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f  ad-write (but no
270b0 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20  t create) .**   
270c0 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20    access, as if 
270d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
270e0 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53  WRITE (but not S
270f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
27100 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62  E) had .**     b
27110 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20  een set. ^Value 
27120 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c  "rwc" is equival
27130 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62  ent to setting b
27140 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49  oth .**     SQLI
27150 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
27160 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45  E and SQLITE_OPE
27170 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74  N_CREATE.  ^If t
27180 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
27190 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20  s.**     set to 
271a0 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20  "memory" then a 
271b0 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20  pure [in-memory 
271c0 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e  database] that n
271d0 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20  ever reads.**   
271e0 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d    or writes from
271f0 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e   disk is used. ^
27200 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74  It is an error t
27210 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75  o specify a valu
27220 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65  e for.**     the
27230 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
27240 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73  that is less res
27250 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68  trictive than th
27260 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a  at specified by.
27270 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73  **     the flags
27280 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74   passed in the t
27290 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
272a0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
272b0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
272c0 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20  > <b>cache</b>: 
272d0 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d  ^The cache param
272e0 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
272f0 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65  to either "share
27300 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72  d" or.**     "pr
27310 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67  ivate". ^Setting
27320 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20   it to "shared" 
27330 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
27340 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20   setting the.** 
27350 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
27360 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20  SHAREDCACHE bit 
27370 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  in the flags arg
27380 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a  ument passed to.
27390 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f  **     sqlite3_o
273a0 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69  pen_v2(). ^Setti
273b0 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72  ng the cache par
273c0 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61  ameter to "priva
273d0 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65  te" is .**     e
273e0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
273f0 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  ting the SQLITE_
27400 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
27410 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49  E bit..**     ^I
27420 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
27430 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
27440 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61  the "cache" para
27450 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74  meter is present
27460 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49   in.**     a URI
27470 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76   filename, its v
27480 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61  alue overrides a
27490 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75  ny behavior requ
274a0 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67  ested by setting
274b0 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
274c0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
274d0 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   or SQLITE_OPEN_
274e0 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67  SHAREDCACHE flag
274f0 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
27500 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20  >psow</b>: ^The 
27510 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69  psow parameter i
27520 6e 64 69 63 61 74 65 73 20 77 68 65 74 68 65 72  ndicates whether
27530 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20   or not the.**  
27540 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76     [powersafe ov
27550 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74  erwrite] propert
27560 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e  y does or does n
27570 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a  ot apply to the.
27580 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d  **     storage m
27590 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68  edia on which th
275a0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
275b0 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20  resides..**.**  
275c0 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f  <li> <b>nolock</
275d0 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20  b>: ^The nolock 
275e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
275f0 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72  oolean query par
27600 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68  ameter.**     wh
27610 69 63 68 20 69 66 20 73 65 74 20 64 69 73 61 62  ich if set disab
27620 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67  les file locking
27630 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75   in rollback jou
27640 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69  rnal modes.  Thi
27650 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66  s.**     is usef
27660 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67  ul for accessing
27670 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61   a database on a
27680 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74   filesystem that
27690 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20   does not.**    
276a0 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67   support locking
276b0 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74  .  Caution:  Dat
276c0 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
276d0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
276e0 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d   two.**     or m
276f0 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20 77 72  ore processes wr
27700 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20  ite to the same 
27710 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79  database and any
27720 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a   one of those.**
27730 20 20 20 20 20 70 72 6f 63 65 73 73 65 73 20 75       processes u
27740 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a  ses nolock=1..**
27750 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d  .**  <li> <b>imm
27760 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65  utable</b>: ^The
27770 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d   immutable param
27780 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61  eter is a boolea
27790 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70  n query.**     p
277a0 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e  arameter that in
277b0 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65  dicates that the
277c0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
277d0 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20  s stored on.**  
277e0 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64     read-only med
277f0 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74  ia.  ^When immut
27800 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c  able is set, SQL
27810 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
27820 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61   the.**     data
27830 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74  base file cannot
27840 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65   be changed, eve
27850 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73 20 77  n by a process w
27860 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20  ith higher.**   
27870 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64    privilege, and
27880 20 73 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   so the database
27890 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d   is opened read-
278a0 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63  only and all loc
278b0 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20  king.**     and 
278c0 63 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e  change detection
278d0 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43   is disabled.  C
278e0 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20  aution: Setting 
278f0 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a  the immutable.**
27900 20 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e       property on
27910 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
27920 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61   that does in fa
27930 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65  ct change can re
27940 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69  sult.**     in i
27950 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79 20 72  ncorrect query r
27960 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53  esults and/or [S
27970 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65  QLITE_CORRUPT] e
27980 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65  rrors..**     Se
27990 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f  e also: [SQLITE_
279a0 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d  IOCAP_IMMUTABLE]
279b0 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c  ..**       .** <
279c0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63  /ul>.**.** ^Spec
279d0 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
279e0 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  n parameter in t
279f0 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
27a00 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e  nt of a URI is n
27a10 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20  ot an.** error. 
27a20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
27a30 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
27a40 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69   understand addi
27a50 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20  tional query.** 
27a60 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65  parameters.  See
27a70 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74   "[query paramet
27a80 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c  ers with special
27a90 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69   meaning to SQLi
27aa0 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69  te]" for.** addi
27ab0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
27ac0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  on..**.** [[URI 
27ad0 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
27ae0 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65  s]] <h3>URI file
27af0 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68  name examples</h
27b00 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20  3>.**.** <table 
27b10 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e  border="1" align
27b20 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64  =center cellpadd
27b30 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  ing=5>.** <tr><t
27b40 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  h> URI filenames
27b50 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a   <th> Results.**
27b60 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
27b70 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
27b80 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
27b90 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
27ba0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
27bb0 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74  directory..** <t
27bc0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
27bd0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62  e/fred/data.db<b
27be0 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  r>.**          f
27bf0 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64  ile:///home/fred
27c00 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a  /data.db <br> .*
27c10 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
27c20 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65  //localhost/home
27c30 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
27c40 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  r> <td> .**     
27c50 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61       Open the da
27c60 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f  tabase file "/ho
27c70 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
27c80 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
27c90 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f  le://darkstar/ho
27ca0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
27cb0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
27cc0 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72    An error. "dar
27cd0 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20  kstar" is not a 
27ce0 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f  recognized autho
27cf0 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  rity..** <tr><td
27d00 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70   style="white-sp
27d10 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a  ace:nowrap"> .**
27d20 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
27d30 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32  //C:/Documents%2
27d40 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f  0and%20Settings/
27d50 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74  fred/Desktop/dat
27d60 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e  a.db.**     <td>
27d70 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f   Windows only: O
27d80 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
27d90 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73  ta.db" on fred's
27da0 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76   desktop on driv
27db0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a  e.**          C:
27dc0 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
27dd0 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20  %20 escaping in 
27de0 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20  this example is 
27df0 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a  not strictly .**
27e00 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73            necess
27e10 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72  ary - space char
27e20 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73  acters can be us
27e30 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20  ed literally.** 
27e40 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20           in URI 
27e50 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74  filenames..** <t
27e60 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
27e70 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68  .db?mode=ro&cach
27e80 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a  e=private <td> .
27e90 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
27ea0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
27eb0 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
27ec0 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61  irectory for rea
27ed0 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a  d-only access..*
27ee0 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72  *          Regar
27ef0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
27f00 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63   or not shared-c
27f10 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61  ache mode is ena
27f20 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  bled by.**      
27f30 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65      default, use
27f40 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65   a private cache
27f50 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
27f60 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
27f70 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64  ta.db?vfs=unix-d
27f80 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20  otfile <td>.**  
27f90 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
27fa0 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  e "/home/fred/da
27fb0 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20  ta.db". Use the 
27fc0 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69  special VFS "uni
27fd0 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20  x-dotfile".**   
27fe0 20 20 20 20 20 20 20 74 68 61 74 20 75 73 65 73         that uses
27ff0 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c   dot-files in pl
28000 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76  ace of posix adv
28010 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a  isory locking..*
28020 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
28030 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61  data.db?mode=rea
28040 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20  donly <td> .**  
28050 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72          An error
28060 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20  . "readonly" is 
28070 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69  not a valid opti
28080 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65  on for the "mode
28090 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  " parameter..** 
280a0 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e  </table>.**.** ^
280b0 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20  URI hexadecimal 
280c0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
280d0 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f   (%HH) are suppo
280e0 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20  rted within the 
280f0 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72  path and.** quer
28100 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
28110 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63  a URI. A hexadec
28120 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
28130 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66  ence consists of
28140 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69   a.** percent si
28150 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f  gn - "%" - follo
28160 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74  wed by exactly t
28170 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  wo hexadecimal d
28180 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66  igits .** specif
28190 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61  ying an octet va
281a0 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65  lue. ^Before the
281b0 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63   path or query c
281c0 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a  omponents of a.*
281d0 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61  * URI filename a
281e0 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20  re interpreted, 
281f0 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64  they are encoded
28200 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64   using UTF-8 and
28210 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63   all .** hexadec
28220 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
28230 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62  ences replaced b
28240 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20  y a single byte 
28250 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a  containing the.*
28260 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  * corresponding 
28270 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70  octet. If this p
28280 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73  rocess generates
28290 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d   an invalid UTF-
282a0 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74  8 encoding,.** t
282b0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
282c0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
282d0 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
282e0 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  ws users:</b>  T
282f0 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  he encoding used
28300 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d   for the filenam
28310 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66  e argument.** of
28320 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
28330 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
28340 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54  _v2() must be UT
28350 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65  F-8, not whateve
28360 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73  r.** codepage is
28370 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
28380 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63  ed.  Filenames c
28390 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e  ontaining intern
283a0 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61  ational.** chara
283b0 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f  cters must be co
283c0 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38  nverted to UTF-8
283d0 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e   prior to passin
283e0 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73  g them into.** s
283f0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
28400 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
28410 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ()..**.** <b>Not
28420 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e  e to Windows Run
28430 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20  time users:</b> 
28440 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64   The temporary d
28450 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65  irectory must be
28460 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f   set.** prior to
28470 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   calling sqlite3
28480 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
28490 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f  e3_open_v2().  O
284a0 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75  therwise, variou
284b0 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68  s.** features th
284c0 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75  at require the u
284d0 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20  se of temporary 
284e0 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a  files may fail..
284f0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
28500 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  [sqlite3_temp_di
28510 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20  rectory].*/.int 
28520 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
28530 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
28540 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
28550 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
28560 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
28570 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
28580 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
28590 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
285a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
285b0 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
285c0 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
285d0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
285e0 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
285f0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
28600 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
28610 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
28620 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
28630 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
28640 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
28650 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
28660 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
28670 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
28680 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
28690 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
286a0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
286b0 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
286c0 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
286d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
286e0 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
286f0 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
28700 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
28710 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28720 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20  : Obtain Values 
28730 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65  For URI Paramete
28740 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  rs.**.** These a
28750 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69  re utility routi
28760 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56  nes, useful to V
28770 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
28780 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a  ns, that check.*
28790 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61  * to see if a da
287a0 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20  tabase file was 
287b0 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61  a URI that conta
287c0 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20  ined a specific 
287d0 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65  query .** parame
287e0 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f  ter, and if so o
287f0 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65  btains the value
28800 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70   of that query p
28810 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
28820 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61  If F is the data
28830 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f  base filename po
28840 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74  inter passed int
28850 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65  o the xOpen() me
28860 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46  thod of .** a VF
28870 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
28880 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20   when the flags 
28890 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
288a0 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20  en() has one or 
288b0 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20  .** more of the 
288c0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
288d0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ] or [SQLITE_OPE
288e0 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20  N_MAIN_DB] bits 
288f0 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20  set and.** P is 
28900 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
28910 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c  query parameter,
28920 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
28930 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
28940 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  ,P) returns the 
28950 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a  value of the P.*
28960 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69  * parameter if i
28970 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55  t exists or a NU
28980 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20  LL pointer if P 
28990 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20  does not appear 
289a0 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70  as a .** query p
289b0 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20  arameter on F.  
289c0 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20  If P is a query 
289d0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a  parameter of F.*
289e0 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69  * has no explici
289f0 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71  t value, then sq
28a00 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
28a10 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
28a20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
28a30 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
28a40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
28a50 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
28a60 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61  F,P,B) routine a
28a70 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73  ssumes that P is
28a80 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61   a boolean.** pa
28a90 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
28aa0 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20  rns true (1) or 
28ab0 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64  false (0) accord
28ac0 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ing to the value
28ad0 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73  .** of P.  The s
28ae0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
28af0 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
28b00 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
28b10 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c  1) if the.** val
28b20 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61  ue of query para
28b30 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
28b40 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c  f "yes", "true",
28b50 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a   or "on" in any.
28b60 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68  ** case or if th
28b70 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
28b80 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e  ith a non-zero n
28b90 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20  umber.  The .** 
28ba0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
28bb0 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
28bc0 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73  nes returns fals
28bd0 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c  e (0) if the val
28be0 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70  ue of.** query p
28bf0 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
28c00 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73  e of "no", "fals
28c10 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20  e", or "off" in 
28c20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69  any case or.** i
28c30 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
28c40 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69  ns with a numeri
28c50 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73  c zero.  If P is
28c60 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20   not a query.** 
28c70 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f  parameter on F o
28c80 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  r if the value o
28c90 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20  f P is does not 
28ca0 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65  match any of the
28cb0 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20  .** above, then 
28cc0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
28cd0 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
28ce0 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a  ns (B!=0)..**.**
28cf0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
28d00 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f  _int64(F,P,D) ro
28d10 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74  utine converts t
28d20 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e  he value of P in
28d30 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73  to a.** 64-bit s
28d40 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
28d50 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69  d returns that i
28d60 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20  nteger, or D if 
28d70 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78  P does not.** ex
28d80 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c  ist.  If the val
28d90 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74  ue of P is somet
28da0 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
28db0 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e  an integer, then
28dc0 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75  .** zero is retu
28dd0 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20  rned..** .** If 
28de0 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  F is a NULL poin
28df0 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ter, then sqlite
28e00 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
28e10 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  F,P) returns NUL
28e20 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  L and.** sqlite3
28e30 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
28e40 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20  ,B) returns B.  
28e50 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55  If F is not a NU
28e60 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a  LL pointer and.*
28e70 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  * is not a datab
28e80 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  ase file pathnam
28e90 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53  e pointer that S
28ea0 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74  QLite passed int
28eb0 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56  o the xOpen.** V
28ec0 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  FS method, then 
28ed0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
28ee0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
28ef0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
28f00 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69  obably.** undesi
28f10 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  rable..*/.const 
28f20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72  char *sqlite3_ur
28f30 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73  i_parameter(cons
28f40 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
28f50 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
28f60 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69  Param);.int sqli
28f70 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
28f80 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
28f90 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
28fa0 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61  Param, int bDefa
28fb0 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ult);.sqlite3_in
28fc0 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  t64 sqlite3_uri_
28fd0 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72  int64(const char
28fe0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
28ff0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
29000 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29010 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
29020 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45  d Messages.** ME
29030 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
29040 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
29050 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33 5f   recent sqlite3_
29060 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63  * API call assoc
29070 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b  iated with .** [
29080 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
29090 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20 74  ion] D failed, t
290a0 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
290b0 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65 72  errcode(D) inter
290c0 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20  face.** returns 
290d0 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73  the numeric [res
290e0 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78  ult code] or [ex
290f0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
29100 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20  de] for that.** 
29110 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20  API call..** If 
29120 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
29130 41 50 49 20 63 61 6c 6c 20 77 61 73 20 73 75 63  API call was suc
29140 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e  cessful,.** then
29150 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
29160 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65  e from sqlite3_e
29170 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65  rrcode() is unde
29180 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  fined..** ^The s
29190 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
291a0 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74  errcode().** int
291b0 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61  erface is the sa
291c0 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69  me except that i
291d0 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
291e0 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64   the .** [extend
291f0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
29200 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64  even when extend
29210 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
29220 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  are.** disabled.
29230 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29240 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64  te3_errmsg() and
29250 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
29260 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  6() return Engli
29270 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74  sh-language.** t
29280 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
29290 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73  es the error, as
292a0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
292b0 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
292c0 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  vely..** ^(Memor
292d0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
292e0 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
292f0 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
29300 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65  ternally..** The
29310 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
29320 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f  s not need to wo
29330 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e  rry about freein
29340 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a  g the result..**
29350 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72   However, the er
29360 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74  ror string might
29370 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
29380 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62  or deallocated b
29390 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  y.** subsequent 
293a0 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53  calls to other S
293b0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20  QLite interface 
293c0 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a  functions.)^.**.
293d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
293e0 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61  errstr() interfa
293f0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45  ce returns the E
29400 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20  nglish-language 
29410 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73  text.** that des
29420 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75  cribes the [resu
29430 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46  lt code], as UTF
29440 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20  -8..** ^(Memory 
29450 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
29460 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
29470 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
29480 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75  rnally.** and mu
29490 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20  st not be freed 
294a0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
294b0 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  on)^..**.** When
294c0 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
294d0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
294e0 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d   is in use, it m
294f0 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63  ight be the.** c
29500 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e  ase that a secon
29510 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f  d error occurs o
29520 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  n a separate thr
29530 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a  ead in between.*
29540 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68  * the time of th
29550 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e  e first error an
29560 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68  d the call to th
29570 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  ese interfaces..
29580 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70  ** When that hap
29590 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64  pens, the second
295a0 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
295b0 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68  eported since th
295c0 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ese.** interface
295d0 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20  s always report 
295e0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
295f0 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69  result.  To avoi
29600 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20  d.** this, each 
29610 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69  thread can obtai
29620 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20  n exclusive use 
29630 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
29640 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
29650 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73  * by invoking [s
29660 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
29670 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  er]([sqlite3_db_
29680 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72  mutex](D)) befor
29690 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74  e beginning.** t
296a0 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f  o use D and invo
296b0 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
296c0 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69  tex_leave]([sqli
296d0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
296e0 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63  ) after.** all c
296f0 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65  alls to the inte
29700 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65  rfaces listed he
29710 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64  re are completed
29720 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e  ..**.** If an in
29730 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
29740 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  th SQLITE_MISUSE
29750 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
29760 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61   interface.** wa
29770 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72  s invoked incorr
29780 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70  ectly by the app
29790 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68  lication.  In th
297a0 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20  at case, the.** 
297b0 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d  error code and m
297c0 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61  essage may or ma
297d0 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f  y not be set..*/
297e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72  .int sqlite3_err
297f0 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
29800 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  );.int sqlite3_e
29810 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
29820 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f  sqlite3 *db);.co
29830 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
29840 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33  3_errmsg(sqlite3
29850 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
29860 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
29870 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
29880 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
29890 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a  errstr(int);../*
298a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72  .** CAPI3REF: Pr
298b0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
298c0 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
298d0 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73  RDS: {prepared s
298e0 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61  tatement} {prepa
298f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a  red statements}.
29900 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
29910 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
29920 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69   represents a si
29930 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
29940 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 62  nt that.** has b
29950 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74  een compiled int
29960 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e  o binary form an
29970 64 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 65  d is ready to be
29980 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a   evaluated..**.*
29990 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 20  * Think of each 
299a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
299b0 20 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d 70   a separate comp
299c0 75 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 54  uter program.  T
299d0 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
299e0 51 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72 63  QL text is sourc
299f0 65 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70 61  e code.  A prepa
29a00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  red statement ob
29a10 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 20  ject .** is the 
29a20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 20  compiled object 
29a30 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d  code.  All SQL m
29a40 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
29a50 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61   into a.** prepa
29a60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62 65  red statement be
29a70 66 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20 72  fore it can be r
29a80 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  un..**.** The li
29a90 66 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 72  fe-cycle of a pr
29aa0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29ab0 20 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 20   object usually 
29ac0 67 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a  goes like this:.
29ad0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
29ae0 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 70 72  i> Create the pr
29af0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29b00 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
29b10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
29b20 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69  2()]..** <li> Bi
29b30 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 61  nd values to [pa
29b40 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20  rameters] using 
29b50 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
29b60 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74  _*().**      int
29b70 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  erfaces..** <li>
29b80 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
29b90 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
29ba0 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
29bb0 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
29bc0 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 70 72  li> Reset the pr
29bd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29be0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
29bf0 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f  reset()] then go
29c00 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f   back.**      to
29c10 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69   step 2.  Do thi
29c20 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74  s zero or more t
29c30 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65  imes..** <li> De
29c40 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74  stroy the object
29c50 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
29c60 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20  finalize()]..** 
29c70 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66  </ol>.*/.typedef
29c80 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
29c90 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  stmt sqlite3_stm
29ca0 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
29cb0 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d  EF: Run-time Lim
29cc0 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  its.** METHOD: s
29cd0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54  qlite3.**.** ^(T
29ce0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
29cf0 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
29d00 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
29d10 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
29d20 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
29d30 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
29d40 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
29d50 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
29d60 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
29d70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
29d80 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
29d90 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
29da0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
29db0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
29dc0 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
29dd0 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
29de0 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
29df0 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
29e00 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
29e10 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
29e20 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
29e30 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
29e40 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
29e50 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ct.)^.**.** ^If 
29e60 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
29e70 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
29e80 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
29e90 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e   unchanged..** ^
29ea0 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20  (For each limit 
29eb0 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f  category SQLITE_
29ec0 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  LIMIT_<i>NAME</i
29ed0 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  > there is a .**
29ee0 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
29ef0 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
29f00 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
29f10 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72  ime by a C prepr
29f20 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61  ocessor macro ca
29f30 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  lled.** [limits 
29f40 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e  | SQLITE_MAX_<i>
29f50 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54  NAME</i>]..** (T
29f60 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
29f70 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
29f80 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
29f90 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
29fa0 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
29fb0 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
29fc0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
29fd0 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
29fe0 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
29ff0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
2a000 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  ..**.** ^Regardl
2a010 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
2a020 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20  r not the limit 
2a030 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65  was changed, the
2a040 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69   .** [sqlite3_li
2a050 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  mit()] interface
2a060 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69   returns the pri
2a070 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  or value of the 
2a080 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65  limit..** ^Hence
2a090 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75  , to find the cu
2a0a0 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61  rrent value of a
2a0b0 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63   limit without c
2a0c0 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73  hanging it,.** s
2a0d0 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69  imply invoke thi
2a0e0 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68  s interface with
2a0f0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
2a100 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a  eter set to -1..
2a110 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c  **.** Run-time l
2a120 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
2a130 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
2a140 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
2a150 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
2a160 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
2a170 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
2a180 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
2a190 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
2a1a0 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
2a1b0 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
2a1c0 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
2a1d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
2a1e0 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72  t be a.** web br
2a1f0 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
2a200 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
2a210 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
2a220 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
2a230 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
2a240 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
2a250 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
2a260 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
2a270 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
2a280 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
2a290 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
2a2a0 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
2a2b0 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
2a2c0 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
2a2d0 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
2a2e0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
2a2f0 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
2a300 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
2a310 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
2a320 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
2a330 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
2a340 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
2a350 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
2a360 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
2a370 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
2a380 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
2a390 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
2a3a0 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
2a3b0 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
2a3c0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2a3d0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
2a3e0 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
2a3f0 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
2a400 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
2a410 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
2a420 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
2a430 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
2a440 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
2a450 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
2a460 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
2a470 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2a480 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
2a490 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
2a4a0 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
2a4b0 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
2a4c0 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
2a4d0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
2a4e0 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
2a4f0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
2a500 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
2a510 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
2a520 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
2a530 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
2a540 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
2a550 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
2a560 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
2a570 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
2a580 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
2a590 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
2a5a0 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
2a5b0 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
2a5c0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
2a5d0 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
2a5e0 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
2a5f0 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
2a600 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
2a610 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2a620 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
2a630 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2a640 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
2a650 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
2a660 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
2a670 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
2a680 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
2a690 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2a6a0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
2a6b0 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
2a6c0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
2a6d0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
2a6e0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
2a6f0 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
2a700 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73  tement, in bytes
2a710 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2a720 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
2a730 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LUMN]] ^(<dt>SQL
2a740 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
2a750 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2a760 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
2a770 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
2a780 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
2a790 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
2a7a0 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
2a7b0 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61  ELECT] or the ma
2a7c0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
2a7d0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
2a7e0 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
2a7f0 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
2a800 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
2a810 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2a820 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
2a830 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
2a840 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
2a850 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
2a860 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
2a870 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
2a880 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
2a890 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
2a8a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2a8b0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
2a8c0 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  CT]] ^(<dt>SQLIT
2a8d0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
2a8e0 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
2a8f0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2a900 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
2a910 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
2a920 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
2a930 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2a940 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
2a950 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  _OP]] ^(<dt>SQLI
2a960 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
2a970 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2a980 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
2a990 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
2a9a0 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
2a9b0 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
2a9c0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
2a9d0 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
2a9e0 6e 74 2e 20 20 49 66 20 5b 73 71 6c 69 74 65 33  nt.  If [sqlite3
2a9f0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2aa00 72 0a 2a 2a 20 74 68 65 20 65 71 75 69 76 61 6c  r.** the equival
2aa10 65 6e 74 20 74 72 69 65 73 20 74 6f 20 61 6c 6c  ent tries to all
2aa20 6f 63 61 74 65 20 73 70 61 63 65 20 66 6f 72 20  ocate space for 
2aa30 6d 6f 72 65 20 74 68 61 6e 20 74 68 69 73 20 6d  more than this m
2aa40 61 6e 79 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 69  any opcodes.** i
2aa50 6e 20 61 20 73 69 6e 67 6c 65 20 70 72 65 70 61  n a single prepa
2aa60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 61  red statement, a
2aa70 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65  n SQLITE_NOMEM e
2aa80 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
2aa90 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2aaa0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
2aab0 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c  NCTION_ARG]] ^(<
2aac0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2aad0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74  FUNCTION_ARG</dt
2aae0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2aaf0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
2ab00 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75  rguments on a fu
2ab10 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  nction.</dd>)^.*
2ab20 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2ab30 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e  MIT_ATTACHED]] ^
2ab40 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2ab50 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
2ab60 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2ab70 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54  um number of [AT
2ab80 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20  TACH | attached 
2ab90 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64  databases].)^</d
2aba0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
2abb0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
2abc0 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a  TERN_LENGTH]].**
2abd0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2abe0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
2abf0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
2ac00 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2ac10 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
2ac20 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
2ac30 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a  o the [LIKE] or.
2ac40 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  ** [GLOB] operat
2ac50 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ors.</dd>)^.**.*
2ac60 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2ac70 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
2ac80 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
2ac90 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
2aca0 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
2acb0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2acc0 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66   index number of
2acd0 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d   any [parameter]
2ace0 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
2acf0 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ment.)^.**.** [[
2ad00 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
2ad10 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  GGER_DEPTH]] ^(<
2ad20 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2ad30 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64  TRIGGER_DEPTH</d
2ad40 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2ad50 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72  ximum depth of r
2ad60 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69  ecursion for tri
2ad70 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ggers.</dd>)^.**
2ad80 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2ad90 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
2ada0 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  S]] ^(<dt>SQLITE
2adb0 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
2adc0 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  READS</dt>.** <d
2add0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
2ade0 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72  mber of auxiliar
2adf0 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73  y worker threads
2ae00 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a   that a single.*
2ae10 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2ae20 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74  ement] may start
2ae30 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
2ae40 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
2ae50 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
2ae60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ae70 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
2ae80 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
2ae90 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
2aea0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
2aeb0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
2aec0 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
2aed0 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
2aee0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
2aef0 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
2af00 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
2af10 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
2af20 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
2af30 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
2af40 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
2af50 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
2af60 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
2af70 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2af80 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
2af90 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
2afa0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2afb0 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
2afc0 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
2afd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2afe0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
2aff0 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
2b000 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2b010 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
2b020 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
2b030 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2b040 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
2b050 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
2b060 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2b070 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
2b080 41 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31  ADS           11
2b090 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b0a0 3a 20 50 72 65 70 61 72 65 20 46 6c 61 67 73 0a  : Prepare Flags.
2b0b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
2b0c0 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72  tants define var
2b0d0 69 6f 75 73 20 66 6c 61 67 73 20 74 68 61 74 20  ious flags that 
2b0e0 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 69 6e  can be passed in
2b0f0 74 6f 0a 2a 2a 20 22 70 72 65 70 46 6c 61 67 73  to.** "prepFlags
2b100 22 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  " parameter of t
2b110 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
2b120 61 72 65 5f 76 33 28 29 5d 20 61 6e 64 0a 2a 2a  are_v3()] and.**
2b130 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b140 65 31 36 5f 76 33 28 29 5d 20 69 6e 74 65 72 66  e16_v3()] interf
2b150 61 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  aces..**.** New 
2b160 66 6c 61 67 73 20 6d 61 79 20 62 65 20 61 64 64  flags may be add
2b170 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
2b180 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
2b190 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
2b1a0 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f  [SQLITE_PREPARE_
2b1b0 50 45 52 53 49 53 54 45 4e 54 5d 5d 20 5e 28 3c  PERSISTENT]] ^(<
2b1c0 64 74 3e 53 51 4c 49 54 45 5f 50 52 45 50 41 52  dt>SQLITE_PREPAR
2b1d0 45 5f 50 45 52 53 49 53 54 45 4e 54 3c 2f 64 74  E_PERSISTENT</dt
2b1e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c  >.** <dd>The SQL
2b1f0 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53  ITE_PREPARE_PERS
2b200 49 53 54 45 4e 54 20 66 6c 61 67 20 69 73 20 61  ISTENT flag is a
2b210 20 68 69 6e 74 20 74 6f 20 74 68 65 20 71 75 65   hint to the que
2b220 72 79 20 70 6c 61 6e 6e 65 72 0a 2a 2a 20 74 68  ry planner.** th
2b230 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  at the prepared 
2b240 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62  statement will b
2b250 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 61  e retained for a
2b260 20 6c 6f 6e 67 20 74 69 6d 65 20 61 6e 64 0a 2a   long time and.*
2b270 2a 20 70 72 6f 62 61 62 6c 79 20 72 65 75 73 65  * probably reuse
2b280 64 20 6d 61 6e 79 20 74 69 6d 65 73 2e 29 5e 20  d many times.)^ 
2b290 5e 57 69 74 68 6f 75 74 20 74 68 69 73 20 66 6c  ^Without this fl
2b2a0 61 67 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ag, [sqlite3_pre
2b2b0 70 61 72 65 5f 76 33 28 29 5d 0a 2a 2a 20 61 6e  pare_v3()].** an
2b2c0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2b2d0 72 65 31 36 5f 76 33 28 29 5d 20 61 73 73 75 6d  re16_v3()] assum
2b2e0 65 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61  e that the prepa
2b2f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 77 69  red statement wi
2b300 6c 6c 20 0a 2a 2a 20 62 65 20 75 73 65 64 20 6a  ll .** be used j
2b310 75 73 74 20 6f 6e 63 65 20 6f 72 20 61 74 20 6d  ust once or at m
2b320 6f 73 74 20 61 20 66 65 77 20 74 69 6d 65 73 20  ost a few times 
2b330 61 6e 64 20 74 68 65 6e 20 64 65 73 74 72 6f 79  and then destroy
2b340 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
2b350 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2b360 20 72 65 6c 61 74 69 76 65 6c 79 20 73 6f 6f 6e   relatively soon
2b370 2e 20 54 68 65 20 63 75 72 72 65 6e 74 20 69 6d  . The current im
2b380 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 63 74  plementation act
2b390 73 0a 2a 2a 20 6f 6e 20 74 68 69 73 20 68 69 6e  s.** on this hin
2b3a0 74 20 62 79 20 61 76 6f 69 64 69 6e 67 20 74 68  t by avoiding th
2b3b0 65 20 75 73 65 20 6f 66 20 5b 6c 6f 6f 6b 61 73  e use of [lookas
2b3c0 69 64 65 20 6d 65 6d 6f 72 79 5d 20 73 6f 20 61  ide memory] so a
2b3d0 73 20 6e 6f 74 20 74 6f 0a 2a 2a 20 64 65 70 6c  s not to.** depl
2b3e0 65 74 65 20 74 68 65 20 6c 69 6d 69 74 65 64 20  ete the limited 
2b3f0 73 74 6f 72 65 20 6f 66 20 6c 6f 6f 6b 61 73 69  store of lookasi
2b400 64 65 20 6d 65 6d 6f 72 79 2e 20 46 75 74 75 72  de memory. Futur
2b410 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 0a 2a 2a  e versions of.**
2b420 20 53 51 4c 69 74 65 20 6d 61 79 20 61 63 74 20   SQLite may act 
2b430 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 64 69 66  on this hint dif
2b440 66 65 72 65 6e 74 6c 79 2e 0a 2a 2a 20 3c 2f 64  ferently..** </d
2b450 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
2b460 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52  LITE_PREPARE_PER
2b470 53 49 53 54 45 4e 54 20 20 20 20 20 20 20 20 20  SISTENT         
2b480 20 20 20 20 20 30 78 30 31 0a 0a 2f 2a 0a 2a 2a       0x01../*.**
2b490 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
2b4a0 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74  ling An SQL Stat
2b4b0 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  ement.** KEYWORD
2b4c0 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e  S: {SQL statemen
2b4d0 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d  t compiler}.** M
2b4e0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
2b4f0 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73  * CONSTRUCTOR: s
2b500 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2b510 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20  * To execute an 
2b520 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69  SQL statement, i
2b530 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
2b540 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
2b550 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
2b560 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
2b570 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2b580 2e 20 20 4f 72 2c 20 69 6e 20 6f 74 68 65 72 20  .  Or, in other 
2b590 77 6f 72 64 73 2c 20 74 68 65 73 65 20 72 6f 75  words, these rou
2b5a0 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 63 6f 6e  tines.** are con
2b5b0 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20 74 68  structors for th
2b5c0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2b5d0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a  ement] object..*
2b5e0 2a 0a 2a 2a 20 54 68 65 20 70 72 65 66 65 72 72  *.** The preferr
2b5f0 65 64 20 72 6f 75 74 69 6e 65 20 74 6f 20 75 73  ed routine to us
2b600 65 20 69 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  e is [sqlite3_pr
2b610 65 70 61 72 65 5f 76 32 28 29 5d 2e 20 20 54 68  epare_v2()].  Th
2b620 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
2b630 65 70 61 72 65 28 29 5d 20 69 6e 74 65 72 66 61  epare()] interfa
2b640 63 65 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64  ce is legacy and
2b650 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64   should be avoid
2b660 65 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ed..** [sqlite3_
2b670 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 68 61  prepare_v3()] ha
2b680 73 20 61 6e 20 65 78 74 72 61 20 22 70 72 65 70  s an extra "prep
2b690 46 6c 61 67 73 22 20 6f 70 74 69 6f 6e 20 74 68  Flags" option th
2b6a0 61 74 20 69 73 20 75 73 65 64 0a 2a 2a 20 66 6f  at is used.** fo
2b6b0 72 20 73 70 65 63 69 61 6c 20 70 75 72 70 6f 73  r special purpos
2b6c0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 73  es..**.** The us
2b6d0 65 20 6f 66 20 74 68 65 20 55 54 46 2d 38 20 69  e of the UTF-8 i
2b6e0 6e 74 65 72 66 61 63 65 73 20 69 73 20 70 72 65  nterfaces is pre
2b6f0 66 65 72 72 65 64 2c 20 61 73 20 53 51 4c 69 74  ferred, as SQLit
2b700 65 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 64  e currently.** d
2b710 6f 65 73 20 61 6c 6c 20 70 61 72 73 69 6e 67 20  oes all parsing 
2b720 75 73 69 6e 67 20 55 54 46 2d 38 2e 20 20 54 68  using UTF-8.  Th
2b730 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72 66 61  e UTF-16 interfa
2b740 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
2b750 0a 2a 2a 20 61 73 20 61 20 63 6f 6e 76 65 6e 69  .** as a conveni
2b760 65 6e 63 65 2e 20 20 54 68 65 20 55 54 46 2d 31  ence.  The UTF-1
2b770 36 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72  6 interfaces wor
2b780 6b 20 62 79 20 63 6f 6e 76 65 72 74 69 6e 67 20  k by converting 
2b790 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 74 65 78  the.** input tex
2b7a0 74 20 69 6e 74 6f 20 55 54 46 2d 38 2c 20 74 68  t into UTF-8, th
2b7b0 65 6e 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  en invoking the 
2b7c0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 55 54  corresponding UT
2b7d0 46 2d 38 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  F-8 interface..*
2b7e0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
2b7f0 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69  rgument, "db", i
2b800 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  s a [database co
2b810 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e  nnection] obtain
2b820 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69  ed from a.** pri
2b830 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
2b840 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ll to [sqlite3_o
2b850 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
2b860 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a  _open_v2()] or.*
2b870 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
2b880 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62  6()].  The datab
2b890 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
2b8a0 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65  ust not have bee
2b8b0 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  n closed..**.** 
2b8c0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
2b8d0 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20  ent, "zSql", is 
2b8e0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  the statement to
2b8f0 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e   be compiled, en
2b900 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68  coded.** as eith
2b910 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
2b920 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  16.  The sqlite3
2b930 5f 70 72 65 70 61 72 65 28 29 2c 20 73 71 6c 69  _prepare(), sqli
2b940 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2b950 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  ,.** and sqlite3
2b960 5f 70 72 65 70 61 72 65 5f 76 33 28 29 0a 2a 2a  _prepare_v3().**
2b970 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
2b980 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
2b990 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 2c 20  e3_prepare16(), 
2b9a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2b9b0 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73  6_v2(),.** and s
2b9c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2b9d0 5f 76 33 28 29 20 75 73 65 20 55 54 46 2d 31 36  _v3() use UTF-16
2b9e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2b9f0 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
2ba00 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
2ba10 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
2ba20 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
2ba30 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2ba40 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70  . ^If nByte is p
2ba50 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74  ositive, then it
2ba60 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
2ba70 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64 20  r of bytes read 
2ba80 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20  from zSql.  ^If 
2ba90 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74  nByte is zero, t
2baa0 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a  hen no prepared.
2bab0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ** statement is 
2bac0 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66  generated..** If
2bad0 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77   the caller know
2bae0 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  s that the suppl
2baf0 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
2bb00 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
2bb10 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61  en.** there is a
2bb20 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e   small performan
2bb30 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
2bb40 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
2bb50 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a   parameter that.
2bb60 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
2bb70 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2bb80 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
2bb90 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a  >including</i>.*
2bba0 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e  * the nul-termin
2bbb0 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ator..**.** ^If 
2bbc0 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
2bbd0 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
2bbe0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
2bbf0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
2bc00 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
2bc10 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
2bc20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
2bc30 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
2bc40 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
2bc50 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
2bc60 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
2bc70 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
2bc80 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
2bc90 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
2bca0 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
2bcb0 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
2bcc0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
2bcd0 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
2bce0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2bcf0 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
2bd00 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
2bd10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2bd20 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
2bd30 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
2bd40 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
2bd50 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
2bd60 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
2bd70 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
2bd80 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
2bd90 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
2bda0 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
2bdb0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
2bdc0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
2bdd0 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
2bde0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
2bdf0 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
2be00 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
2be10 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
2be20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2be30 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
2be40 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
2be50 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
2be60 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
2be70 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
2be80 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
2be90 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
2bea0 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
2beb0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
2bec0 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
2bed0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
2bee0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2bef0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
2bf00 61 72 65 5f 76 32 28 29 2c 20 73 71 6c 69 74 65  are_v2(), sqlite
2bf10 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 2c 20  3_prepare_v3(), 
2bf20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2bf30 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73  6_v2(),.** and s
2bf40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2bf50 5f 76 33 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v3() interfaces
2bf60 20 61 72 65 20 72 65 63 6f 6d 6d 65 6e 64 65 64   are recommended
2bf70 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
2bf80 67 72 61 6d 73 2e 0a 2a 2a 20 54 68 65 20 6f 6c  grams..** The ol
2bf90 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 28  der interfaces (
2bfa0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2bfb0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
2bfc0 65 70 61 72 65 31 36 28 29 29 0a 2a 2a 20 61 72  epare16()).** ar
2bfd0 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62  e retained for b
2bfe0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
2bff0 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
2c000 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
2c010 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65  aged..** ^In the
2c020 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73   "vX" interfaces
2c030 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
2c040 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
2c050 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
2c060 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
2c070 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
2c080 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
2c090 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
2c0a0 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
2c0b0 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
2c0c0 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
2c0d0 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69   to.** behave di
2c0e0 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72  fferently in thr
2c0f0 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ee ways:.**.** <
2c100 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  ol>.** <li>.** ^
2c110 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
2c120 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20  schema changes, 
2c130 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72  instead of retur
2c140 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48  ning [SQLITE_SCH
2c150 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c  EMA] as it.** al
2c160 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c  ways used to do,
2c170 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2c180 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ] will automatic
2c190 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74  ally recompile t
2c1a0 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  he SQL.** statem
2c1b0 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72  ent and try to r
2c1c0 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20  un it again. As 
2c1d0 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f  many as [SQLITE_
2c1e0 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59  MAX_SCHEMA_RETRY
2c1f0 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c  ].** retries wil
2c200 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73  l occur before s
2c210 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67 69  qlite3_step() gi
2c220 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75 72  ves up and retur
2c230 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20  ns an error..** 
2c240 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
2c250 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72  .** ^When an err
2c260 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69  or occurs, [sqli
2c270 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
2c280 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74   return one of t
2c290 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b  he detailed.** [
2c2a0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20  error codes] or 
2c2b0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
2c2c0 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65  codes].  ^The le
2c2d0 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
2c2e0 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74  s that.** [sqlit
2c2f0 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
2c300 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
2c310 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45  eneric [SQLITE_E
2c320 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
2c330 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70  e.** and the app
2c340 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68  lication would h
2c350 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65  ave to make a se
2c360 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cond call to [sq
2c370 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
2c380 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  * in order to fi
2c390 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
2c3a0 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  g cause of the p
2c3b0 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65  roblem. With the
2c3c0 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a   "v2" prepare.**
2c3d0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
2c3e0 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73   underlying reas
2c3f0 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72  on for the error
2c400 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
2c410 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c  ediately..** </l
2c420 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
2c430 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
2c440 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f  c value bound to
2c450 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f   [parameter | ho
2c460 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  st parameter] in
2c470 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63   the .** WHERE c
2c480 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c  lause might infl
2c490 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65  uence the choice
2c4a0 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66   of query plan f
2c4b0 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a  or a statement,.
2c4c0 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74  ** then the stat
2c4d0 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75  ement will be au
2c4e0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
2c4f0 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68  mpiled, as if th
2c500 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a  ere had been .**
2c510 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
2c520 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20  , on the first  
2c530 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2c540 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20   call following 
2c550 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f  any change.** to
2c560 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
2c570 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e  nd_text | bindin
2c580 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72  gs] of that [par
2c590 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68  ameter]. .** ^Th
2c5a0 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
2c5b0 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65   of WHERE-clause
2c5c0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67   [parameter] mig
2c5d0 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
2c5e0 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71   .** choice of q
2c5f0 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65  uery plan if the
2c600 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2c610 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  e left-hand side
2c620 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20   of a [LIKE].** 
2c630 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  or [GLOB] operat
2c640 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72  or or if the par
2c650 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72  ameter is compar
2c660 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64  ed to an indexed
2c670 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74   column.** and t
2c680 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  he [SQLITE_ENABL
2c690 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65  E_STAT3] compile
2c6a0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
2c6b0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69  enabled..** </li
2c6c0 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ol>.**.**
2c6d0 20 3c 70 3e 5e 73 71 6c 69 74 65 33 5f 70 72 65   <p>^sqlite3_pre
2c6e0 70 61 72 65 5f 76 33 28 29 20 64 69 66 66 65 72  pare_v3() differ
2c6f0 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 70  s from sqlite3_p
2c700 72 65 70 61 72 65 5f 76 32 28 29 20 6f 6e 6c 79  repare_v2() only
2c710 20 69 6e 20 68 61 76 69 6e 67 0a 2a 2a 20 74 68   in having.** th
2c720 65 20 65 78 74 72 61 20 70 72 65 70 46 6c 61 67  e extra prepFlag
2c730 73 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69  s parameter, whi
2c740 63 68 20 69 73 20 61 20 62 69 74 20 61 72 72 61  ch is a bit arra
2c750 79 20 63 6f 6e 73 69 73 74 69 6e 67 20 6f 66 20  y consisting of 
2c760 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20  zero or.** more 
2c770 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 50  of the [SQLITE_P
2c780 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e  REPARE_PERSISTEN
2c790 54 7c 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  T|SQLITE_PREPARE
2c7a0 5f 2a 5d 20 66 6c 61 67 73 2e 20 20 5e 54 68 65  _*] flags.  ^The
2c7b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
2c7c0 61 72 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61  are_v2() interfa
2c7d0 63 65 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79  ce works exactly
2c7e0 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20   the same as.** 
2c7f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2c800 76 33 28 29 20 77 69 74 68 20 61 20 7a 65 72 6f  v3() with a zero
2c810 20 70 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d   prepFlags param
2c820 65 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  eter..*/.int sql
2c830 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20  ite3_prepare(.  
2c840 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2c850 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2c860 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
2c870 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
2c880 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
2c890 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
2c8a0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2c8b0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2c8c0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2c8d0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2c8e0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2c8f0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2c900 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2c910 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2c920 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2c930 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2c940 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2c950 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2c960 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
2c970 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2c980 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
2c990 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2c9a0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2c9b0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2c9c0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2c9d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2c9e0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
2c9f0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2ca00 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2ca10 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2ca20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2ca30 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2ca40 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2ca50 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2ca60 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2ca70 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
2ca80 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2ca90 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2caa0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2cab0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
2cac0 65 70 61 72 65 5f 76 33 28 0a 20 20 73 71 6c 69  epare_v3(.  sqli
2cad0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2cae0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2caf0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2cb00 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
2cb10 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
2cb20 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
2cb30 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2cb40 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2cb50 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2cb60 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2cb70 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 6e  tes. */.  unsign
2cb80 65 64 20 69 6e 74 20 70 72 65 70 46 6c 61 67 73  ed int prepFlags
2cb90 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f 72  , /* Zero or mor
2cba0 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  e SQLITE_PREPARE
2cbb0 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71 6c  _ flags */.  sql
2cbc0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2cbd0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2cbe0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2cbf0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
2cc00 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2cc10 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2cc20 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2cc30 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
2cc40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2cc50 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2cc60 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2cc70 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2cc80 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2cc90 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2cca0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2ccb0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
2ccc0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2ccd0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2cce0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2ccf0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2cd00 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2cd10 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2cd20 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2cd30 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2cd40 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
2cd50 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2cd60 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2cd70 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2cd80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
2cd90 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c  pare16_v2(.  sql
2cda0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2cdb0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2cdc0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2cdd0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
2cde0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2cdf0 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
2ce00 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2ce10 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2ce20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2ce30 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2ce40 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
2ce50 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2ce60 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2ce70 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2ce80 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
2ce90 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2cea0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2ceb0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2cec0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
2ced0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2cee0 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v3(.  sqlite3 *d
2cef0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2cf00 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2cf10 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2cf20 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2cf30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2cf40 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
2cf50 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2cf60 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2cf70 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2cf80 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2cf90 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 6e  */.  unsigned in
2cfa0 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20  t prepFlags, /* 
2cfb0 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c  Zero or more SQL
2cfc0 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c 61  ITE_PREPARE_ fla
2cfd0 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  gs */.  sqlite3_
2cfe0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2cff0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2d000 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2d010 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
2d020 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2d030 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2d040 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2d050 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
2d060 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e  I3REF: Retrievin
2d070 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a  g Statement SQL.
2d080 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2d090 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2d0a0 68 65 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50  he sqlite3_sql(P
2d0b0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2d0c0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2d0d0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 55   a copy of the U
2d0e0 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78 74  TF-8.** SQL text
2d0f0 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
2d100 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d110 65 6e 74 5d 20 50 20 69 66 20 50 20 77 61 73 0a  ent] P if P was.
2d120 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 5b 73  ** created by [s
2d130 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2d140 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70  2()], [sqlite3_p
2d150 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 0a 2a 2a  repare_v3()],.**
2d160 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d170 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b 73  e16_v2()], or [s
2d180 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2d190 5f 76 33 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  _v3()]..** ^The 
2d1a0 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2d1b0 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63  _sql(P) interfac
2d1c0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2d1d0 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a 2a  ter to a UTF-8.*
2d1e0 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
2d1f0 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65 78 74  ing the SQL text
2d200 20 6f 66 20 70 72 65 70 61 72 65 64 20 73 74 61   of prepared sta
2d210 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a 2a  tement P with.**
2d220 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65   [bound paramete
2d230 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a 2a  rs] expanded..**
2d240 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
2d250 65 2c 20 69 66 20 61 20 70 72 65 70 61 72 65 64  e, if a prepared
2d260 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 72   statement is cr
2d270 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 20  eated using the 
2d280 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45 4c  SQL.** text "SEL
2d290 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 61  ECT $abc,:xyz" a
2d2a0 6e 64 20 69 66 20 70 61 72 61 6d 65 74 65 72 20  nd if parameter 
2d2b0 24 61 62 63 20 69 73 20 62 6f 75 6e 64 20 74 6f  $abc is bound to
2d2c0 20 69 6e 74 65 67 65 72 20 32 33 34 35 0a 2a 2a   integer 2345.**
2d2d0 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 3a   and parameter :
2d2e0 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c 20  xyz is unbound, 
2d2f0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 71 6c  then sqlite3_sql
2d300 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  () will return.*
2d310 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
2d320 74 72 69 6e 67 2c 20 22 53 45 4c 45 43 54 20 24  tring, "SELECT $
2d330 61 62 63 2c 3a 78 79 7a 22 20 62 75 74 20 73 71  abc,:xyz" but sq
2d340 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2d350 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74  ql().** will ret
2d360 75 72 6e 20 22 53 45 4c 45 43 54 20 32 33 34 35  urn "SELECT 2345
2d370 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ,NULL".)^.**.** 
2d380 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70  ^The sqlite3_exp
2d390 61 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e 74 65  anded_sql() inte
2d3a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55  rface returns NU
2d3b0 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65  LL if insufficie
2d3c0 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 20  nt memory.** is 
2d3d0 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f 6c  available to hol
2d3e0 64 20 74 68 65 20 72 65 73 75 6c 74 2c 20 6f 72  d the result, or
2d3f0 20 69 66 20 74 68 65 20 72 65 73 75 6c 74 20 77   if the result w
2d400 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a  ould exceed the.
2d410 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73  ** the maximum s
2d420 74 72 69 6e 67 20 6c 65 6e 67 74 68 20 64 65 74  tring length det
2d430 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 5b  ermined by the [
2d440 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
2d450 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  GTH]..**.** ^The
2d460 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53   [SQLITE_TRACE_S
2d470 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69  IZE_LIMIT] compi
2d480 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 6c  le-time option l
2d490 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f  imits the size o
2d4a0 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61 6d  f.** bound param
2d4b0 65 74 65 72 20 65 78 70 61 6e 73 69 6f 6e 73 2e  eter expansions.
2d4c0 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f    ^The [SQLITE_O
2d4d0 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69  MIT_TRACE] compi
2d4e0 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
2d4f0 6e 20 63 61 75 73 65 73 20 73 71 6c 69 74 65 33  n causes sqlite3
2d500 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20  _expanded_sql() 
2d510 74 6f 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  to always return
2d520 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
2d530 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65  e string returne
2d540 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71 6c  d by sqlite3_sql
2d550 28 50 29 20 69 73 20 6d 61 6e 61 67 65 64 20 62  (P) is managed b
2d560 79 20 53 51 4c 69 74 65 20 61 6e 64 20 69 73 0a  y SQLite and is.
2d570 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
2d580 20 66 72 65 65 64 20 77 68 65 6e 20 74 68 65 20   freed when the 
2d590 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d5a0 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 2e  nt is finalized.
2d5b0 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20  .** ^The string 
2d5c0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2d5d0 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2d5e0 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68 65  (P), on the othe
2d5f0 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62  r hand,.** is ob
2d600 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
2d610 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
2d620 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65 65 20  nd must be free 
2d630 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
2d640 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e 67  on.** by passing
2d650 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
2d660 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  free()]..*/.cons
2d670 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2d680 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
2d690 20 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72 20 2a   *pStmt);.char *
2d6a0 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2d6b0 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
2d6c0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2d6d0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
2d6e0 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
2d6f0 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73  Statement Writes
2d700 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a   The Database.**
2d710 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2d720 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2d730 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2d740 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
2d750 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
2d760 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a   (non-zero) if.*
2d770 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  * and only if th
2d780 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2d790 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e  ement] X makes n
2d7a0 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
2d7b0 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
2d7c0 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
2d7d0 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
2d7e0 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
2d7f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2d800 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
2d810 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
2d820 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
2d830 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
2d840 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
2d850 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
2d860 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
2d870 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
2d880 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
2d890 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
2d8a0 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
2d8b0 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
2d8c0 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
2d8d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
2d8e0 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
2d8f0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2d900 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
2d910 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
2d920 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
2d930 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
2d940 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
2d950 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
2d960 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
2d970 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
2d980 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
2d990 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
2d9a0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
2d9b0 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
2d9c0 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
2d9d0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2d9e0 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
2d9f0 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
2da00 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
2da10 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
2da20 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
2da30 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
2da40 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
2da50 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
2da60 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
2da70 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2da80 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
2da90 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
2daa0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
2dab0 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
2dac0 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
2dad0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
2dae0 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
2daf0 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
2db00 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
2db10 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
2db20 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
2db30 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
2db40 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
2db50 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
2db60 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
2db70 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2db80 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
2db90 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
2dba0 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
2dbb0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
2dbc0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
2dbd0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2dbe0 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
2dbf0 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
2dc00 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
2dc10 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
2dc20 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
2dc30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2dc40 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
2dc50 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2dc60 6e 73 20 74 72 75 65 20 66 6f 72 20 5b 42 45 47  ns true for [BEG
2dc70 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b 42 45  IN] since.** [BE
2dc80 47 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65 74 73  GIN] merely sets
2dc90 20 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67 73 2c   internal flags,
2dca0 20 62 75 74 20 74 68 65 20 5b 42 45 47 49 4e 7c   but the [BEGIN|
2dcb0 42 45 47 49 4e 20 49 4d 4d 45 44 49 41 54 45 5d  BEGIN IMMEDIATE]
2dcc0 20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c 42   and.** [BEGIN|B
2dcd0 45 47 49 4e 20 45 58 43 4c 55 53 49 56 45 5d 20  EGIN EXCLUSIVE] 
2dce0 63 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f 75 63  commands do touc
2dcf0 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  h the database a
2dd00 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nd so.** sqlite3
2dd10 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
2dd20 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 66   returns false f
2dd30 6f 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e 64  or those command
2dd40 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
2dd50 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2dd60 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2dd70 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2dd80 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
2dd90 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53   If A Prepared S
2dda0 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65  tatement Has Bee
2ddb0 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f  n Reset.** METHO
2ddc0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2ddd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2dde0 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20  e3_stmt_busy(S) 
2ddf0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2de00 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
2de10 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ) if the.** [pre
2de20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2de30 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70   S has been step
2de40 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63  ped at least onc
2de50 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  e using .** [sql
2de60 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75  ite3_step(S)] bu
2de70 74 20 68 61 73 20 6e 65 69 74 68 65 72 20 72 75  t has neither ru
2de80 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  n to completion 
2de90 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51  (returned.** [SQ
2dea0 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20  LITE_DONE] from 
2deb0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2dec0 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72  ]) nor.** been r
2ded0 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  eset using [sqli
2dee0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20  te3_reset(S)].  
2def0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
2df00 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74  t_busy(S).** int
2df10 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66  erface returns f
2df20 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e  alse if S is a N
2df30 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66  ULL pointer.  If
2df40 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20   S is not a .** 
2df50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
2df60 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65   is not a pointe
2df70 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72  r to a valid [pr
2df80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2df90 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65  ].** object, the
2dfa0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
2dfb0 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
2dfc0 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72  probably undesir
2dfd0 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  able..**.** This
2dfe0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
2dff0 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e  e used in combin
2e000 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e  ation [sqlite3_n
2e010 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74  ext_stmt()].** t
2e020 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65  o locate all pre
2e030 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2e040 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2e050 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20   a database .** 
2e060 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
2e070 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62  are in need of b
2e080 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69  eing reset.  Thi
2e090 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a  s can be used,.*
2e0a0 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  * for example, i
2e0b0 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75  n diagnostic rou
2e0c0 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20  tines to search 
2e0d0 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a  for prepared .**
2e0e0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
2e0f0 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74   are holding a t
2e100 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e  ransaction open.
2e110 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2e120 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65  stmt_busy(sqlite
2e130 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2e140 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d   CAPI3REF: Dynam
2e150 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c  ically Typed Val
2e160 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  ue Object.** KEY
2e170 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65  WORDS: {protecte
2e180 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
2e190 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   {unprotected sq
2e1a0 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a  lite3_value}.**.
2e1b0 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  ** SQLite uses t
2e1c0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
2e1d0 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65   object to repre
2e1e0 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a  sent all values.
2e1f0 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73  ** that can be s
2e200 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62  tored in a datab
2e210 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74  ase table. SQLit
2e220 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74  e uses dynamic t
2e230 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65  yping.** for the
2e240 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65   values it store
2e250 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72  s.  ^Values stor
2e260 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61  ed in sqlite3_va
2e270 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63  lue objects.** c
2e280 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20  an be integers, 
2e290 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
2e2a0 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20  alues, strings, 
2e2b0 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a  BLOBs, or NULL..
2e2c0 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33  **.** An sqlite3
2e2d0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
2e2e0 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f  y be either "pro
2e2f0 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72  tected" or "unpr
2e300 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d  otected"..** Som
2e310 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  e interfaces req
2e320 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64  uire a protected
2e330 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
2e340 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   Other interface
2e350 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74  s.** will accept
2e360 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63   either a protec
2e370 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ted or an unprot
2e380 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e390 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e  lue..** Every in
2e3a0 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63  terface that acc
2e3b0 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c  epts sqlite3_val
2e3c0 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65  ue arguments spe
2e3d0 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65  cifies.** whethe
2e3e0 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75  r or not it requ
2e3f0 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64  ires a protected
2e400 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
2e410 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
2e420 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e  _value_dup()] in
2e430 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
2e440 73 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74  sed to construct
2e450 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65   a new .** prote
2e460 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2e470 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f  ue from an unpro
2e480 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2e490 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
2e4a0 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
2e4b0 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
2e4c0 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
2e4d0 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
2e4e0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
2e4f0 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74   An internal mut
2e500 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
2e510 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71   protected.** sq
2e520 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2e530 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20  ct but no mutex 
2e540 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75  is held for an u
2e550 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
2e560 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2e570 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ct.  If SQLite i
2e580 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65  s compiled to be
2e590 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
2e5a0 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54  .** (with [SQLIT
2e5b0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
2e5c0 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
2e5d0 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
2e5e0 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
2e5f0 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  or if SQLite is 
2e600 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65  run in one of re
2e610 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65  duced mutex mode
2e620 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  s .** [SQLITE_CO
2e630 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2e640 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  D] or [SQLITE_CO
2e650 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
2e660 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ].** then there 
2e670 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
2e680 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
2e690 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
2e6a0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2e6b0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
2e6c0 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65   they can be use
2e6d0 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
2e6e0 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  y.  However,.** 
2e6f0 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
2e700 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20   portability it 
2e710 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
2e720 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
2e730 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74  .** still make t
2e740 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  he distinction b
2e750 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
2e760 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
2e770 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2e780 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
2e790 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
2e7a0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
2e7b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
2e7c0 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74  lue objects that
2e7d0 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70   are passed as p
2e7e0 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74  arameters into t
2e7f0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
2e800 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61  tion of [applica
2e810 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2e820 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20   functions] are 
2e830 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54  protected..** ^T
2e840 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
2e850 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2e860 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
2e870 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
2e880 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a  is unprotected..
2e890 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73  ** Unprotected s
2e8a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2e8b0 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ects may only be
2e8c0 20 75 73 65 64 20 61 73 20 61 72 67 75 6d 65 6e   used as argumen
2e8d0 74 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  ts.** to [sqlite
2e8e0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
2e8f0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ], [sqlite3_bind
2e900 5f 76 61 6c 75 65 28 29 5d 2c 20 61 6e 64 0a 2a  _value()], and.*
2e910 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
2e920 5f 64 75 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  _dup()]..** The 
2e930 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2e940 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61  lob | sqlite3_va
2e950 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69  lue_type()] fami
2e960 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  ly of.** interfa
2e970 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74  ces require prot
2e980 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e990 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a  lue objects..*/.
2e9a0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2e9b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 73 71 6c  qlite3_value sql
2e9c0 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
2e9d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
2e9e0 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
2e9f0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
2ea00 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
2ea10 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
2ea20 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
2ea30 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
2ea40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2ea50 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e  object.  ^A poin
2ea60 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
2ea70 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
2ea80 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
2ea90 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
2eaa0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2eab0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2eac0 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
2ead0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2eae0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
2eaf0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
2eb00 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
2eb10 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
2eb20 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
2eb30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
2eb40 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
2eb50 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
2eb60 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2eb70 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
2eb80 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
2eb90 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
2eba0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
2ebb0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
2ebc0 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
2ebd0 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
2ebe0 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
2ebf0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2ec00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
2ec10 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
2ec20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ec30 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
2ec40 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
2ec50 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52  ements.** KEYWOR
2ec60 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  DS: {host parame
2ec70 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ter} {host param
2ec80 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72  eters} {host par
2ec90 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20  ameter name}.** 
2eca0 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70  KEYWORDS: {SQL p
2ecb0 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70  arameter} {SQL p
2ecc0 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61  arameters} {para
2ecd0 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a  meter binding}.*
2ece0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2ecf0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49  3_stmt.**.** ^(I
2ed00 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
2ed10 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74  ent text input t
2ed20 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
2ed30 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
2ed40 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
2ed50 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
2ed60 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72  placed by a [par
2ed70 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74  ameter] that mat
2ed80 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c  ches one of foll
2ed90 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74  owing.** templat
2eda0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
2edb0 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
2edc0 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
2edd0 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
2ede0 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
2edf0 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
2ee00 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65   In the template
2ee10 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70  s above, NNN rep
2ee20 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67  resents an integ
2ee30 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
2ee40 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74  nd VVV represent
2ee50 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69  s an alphanumeri
2ee60 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20  c identifier.)^ 
2ee70 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20   ^The values of 
2ee80 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
2ee90 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
2eea0 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
2eeb0 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
2eec0 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
2eed0 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
2eee0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2eef0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
2ef00 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
2ef10 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2ef20 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
2ef30 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2ef40 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
2ef50 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
2ef60 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
2ef70 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
2ef80 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
2ef90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2efa0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
2efb0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
2efc0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2efd0 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
2efe0 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
2eff0 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
2f000 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51  ^The leftmost SQ
2f010 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
2f020 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
2f030 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  ^When the same n
2f040 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
2f050 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
2f060 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
2f070 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
2f080 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
2f090 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
2f0a0 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
2f0b0 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
2f0c0 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f  ** ^The index fo
2f0d0 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
2f0e0 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
2f0f0 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
2f100 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2f110 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2f120 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
2f130 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a  .  ^The index.**
2f140 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
2f150 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
2f160 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e  lue of NNN..** ^
2f170 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
2f180 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
2f190 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
2f1a0 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
2f1b0 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
2f1c0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
2f1d0 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
2f1e0 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
2f1f0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
2f200 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
2f210 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
2f220 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
2f230 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
2f240 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2f250 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
2f260 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2f270 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71  ext16().** or sq
2f280 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2f290 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
2f2a0 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ter then the fou
2f2b0 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rth parameter.**
2f2c0 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20   is ignored and 
2f2d0 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69  the end result i
2f2e0 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71  s the same as sq
2f2f0 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
2f300 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  )..**.** ^(In th
2f310 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
2f320 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
2f330 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
2f340 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
2f350 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2f360 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
2f370 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
2f380 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
2f390 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
2f3a0 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
2f3b0 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
2f3c0 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
2f3d0 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68  ers.)^.** ^If th
2f3e0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2f3f0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2f400 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
2f410 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2f420 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  ().** is negativ
2f430 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67  e, then the leng
2f440 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
2f450 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
2f460 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
2f470 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
2f480 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49  terminator..** I
2f490 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2f4a0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2f4b0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
2f4c0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a   negative, then.
2f4d0 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ** the behavior 
2f4e0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2f4f0 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69   If a non-negati
2f500 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ve fourth parame
2f510 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20  ter is provided 
2f520 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2f530 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  text().** or sql
2f540 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2f550 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
2f560 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e  nd_text64() then
2f570 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74  .** that paramet
2f580 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62  er must be the b
2f590 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68  yte offset.** wh
2f5a0 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d  ere the NUL term
2f5b0 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63  inator would occ
2f5c0 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20  ur assuming the 
2f5d0 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a  string were NUL.
2f5e0 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ** terminated.  
2f5f0 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61  If any NUL chara
2f600 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62  cters occur at b
2f610 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73  yte offsets less
2f620 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61   than .** the va
2f630 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74  lue of the fourt
2f640 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e  h parameter then
2f650 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
2f660 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c  tring value will
2f670 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  .** contain embe
2f680 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20  dded NULs.  The 
2f690 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73  result of expres
2f6a0 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20  sions involving 
2f6b0 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20  strings.** with 
2f6c0 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73  embedded NULs is
2f6d0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2f6e0 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
2f6f0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f  ument to the BLO
2f700 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e  B and string bin
2f710 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a  ding interfaces.
2f720 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 74  ** is a destruct
2f730 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f  or used to dispo
2f740 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
2f750 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65  r.** string afte
2f760 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e  r SQLite has fin
2f770 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20  ished with it.  
2f780 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
2f790 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20  is called.** to 
2f7a0 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
2f7b0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76  LOB or string ev
2f7c0 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  en if the call t
2f7d0 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73  o bind API fails
2f7e0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
2f7f0 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  th argument is.*
2f800 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61  * the special va
2f810 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
2f820 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  IC], then SQLite
2f830 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
2f840 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
2f850 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
2f860 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
2f870 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
2f880 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a   to be freed..**
2f890 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
2f8a0 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
2f8b0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
2f8c0 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
2f8d0 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
2f8e0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
2f8f0 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
2f900 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
2f910 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
2f920 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2f930 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
2f940 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 72  ** ^The sixth ar
2f950 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
2f960 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
2f970 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a  must be one of.*
2f980 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  * [SQLITE_UTF8],
2f990 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c   [SQLITE_UTF16],
2f9a0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
2f9b0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ], or [SQLITE_UT
2f9c0 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65  F16LE].** to spe
2f9d0 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e  cify the encodin
2f9e0 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e  g of the text in
2f9f0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
2fa00 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65  eter.  If.** the
2fa10 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20   sixth argument 
2fa20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2fa30 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20  text64() is not 
2fa40 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c  one of the.** al
2fa50 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f  lowed values sho
2fa60 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20  wn above, or if 
2fa70 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
2fa80 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a  g is different.*
2fa90 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64  * from the encod
2faa0 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 79  ing specified by
2fab0 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d   the sixth param
2fac0 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62  eter, then the b
2fad0 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e  ehavior.** is un
2fae0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2faf0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2fb00 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74  _zeroblob() rout
2fb10 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42  ine binds a BLOB
2fb20 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61   of length N tha
2fb30 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77  t.** is filled w
2fb40 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20  ith zeroes.  ^A 
2fb50 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
2fb60 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
2fb70 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
2fb80 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
2fb90 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69  ld its size) whi
2fba0 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
2fbb0 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
2fbc0 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
2fbd0 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
2fbe0 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
2fbf0 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
2fc00 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
2fc10 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a   written using.*
2fc20 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
2fc30 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
2fc40 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  al BLOB I/O] rou
2fc50 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67  tines..** ^A neg
2fc60 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20  ative value for 
2fc70 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73  the zeroblob res
2fc80 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c  ults in a zero-l
2fc90 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a  ength BLOB..**.*
2fca0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2fcb0 69 6e 64 5f 70 6f 69 6e 74 65 72 28 53 2c 49 2c  ind_pointer(S,I,
2fcc0 50 2c 54 2c 44 29 20 72 6f 75 74 69 6e 65 20 63  P,T,D) routine c
2fcd0 61 75 73 65 73 20 74 68 65 20 49 2d 74 68 20 70  auses the I-th p
2fce0 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 5b  arameter in.** [
2fcf0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2fd00 6e 74 5d 20 53 20 74 6f 20 68 61 76 65 20 61 6e  nt] S to have an
2fd10 20 53 51 4c 20 76 61 6c 75 65 20 6f 66 20 4e 55   SQL value of NU
2fd20 4c 4c 2c 20 62 75 74 20 74 6f 20 61 6c 73 6f 20  LL, but to also 
2fd30 62 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  be.** associated
2fd40 20 77 69 74 68 20 74 68 65 20 70 6f 69 6e 74 65   with the pointe
2fd50 72 20 50 20 6f 66 20 74 79 70 65 20 54 2e 20 20  r P of type T.  
2fd60 5e 44 20 69 73 20 65 69 74 68 65 72 20 61 20 4e  ^D is either a N
2fd70 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 0a 2a  ULL pointer or.*
2fd80 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
2fd90 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63   destructor func
2fda0 74 69 6f 6e 20 66 6f 72 20 50 2e 20 5e 53 51 4c  tion for P. ^SQL
2fdb0 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
2fdc0 74 68 65 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f  the.** destructo
2fdd0 72 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c  r D with a singl
2fde0 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 50 20  e argument of P 
2fdf0 77 68 65 6e 20 69 74 20 69 73 20 66 69 6e 69 73  when it is finis
2fe00 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20 50 2e 20  hed using.** P. 
2fe10 20 54 68 65 20 54 20 70 61 72 61 6d 65 74 65 72   The T parameter
2fe20 20 73 68 6f 75 6c 64 20 62 65 20 61 20 73 74 61   should be a sta
2fe30 74 69 63 20 73 74 72 69 6e 67 2c 20 70 72 65 66  tic string, pref
2fe40 65 72 61 62 6c 79 20 61 20 73 74 72 69 6e 67 0a  erably a string.
2fe50 2a 2a 20 6c 69 74 65 72 61 6c 2e 20 54 68 65 20  ** literal. The 
2fe60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69  sqlite3_bind_poi
2fe70 6e 74 65 72 28 29 20 72 6f 75 74 69 6e 65 20 69  nter() routine i
2fe80 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
2fe90 20 5b 70 6f 69 6e 74 65 72 20 70 61 73 73 69 6e   [pointer passin
2fea0 67 20 69 6e 74 65 72 66 61 63 65 5d 20 61 64 64  g interface] add
2feb0 65 64 20 66 6f 72 20 53 51 4c 69 74 65 20 33 2e  ed for SQLite 3.
2fec0 32 30 2e 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  20.0..**.** ^If 
2fed0 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74  any of the sqlit
2fee0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2fef0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2ff00 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
2ff10 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ter.** for the [
2ff20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ff30 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72  nt] or with a pr
2ff40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ff50 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73   for which.** [s
2ff60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
2ff70 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d  as been called m
2ff80 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61  ore recently tha
2ff90 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
2ffa0 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ()],.** then the
2ffb0 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72   call will retur
2ffc0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
2ffd0 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74  ].  If any sqlit
2ffe0 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f  e3_bind_().** ro
2fff0 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20  utine is passed 
30000 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
30010 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20  ement] that has 
30020 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20  been finalized, 
30030 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73  the.** result is
30040 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
30050 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e  robably harmful.
30060 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73  .**.** ^Bindings
30070 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
30080 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
30090 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
300a0 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70  e..** ^Unbound p
300b0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
300c0 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
300d0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
300e0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75  lite3_bind_* rou
300f0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
30100 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
30110 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72  ess or an.** [er
30120 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
30130 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
30140 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f  ..** ^[SQLITE_TO
30150 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72  OBIG] might be r
30160 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 73  eturned if the s
30170 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20  ize of a string 
30180 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65  or BLOB.** excee
30190 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65  ds limits impose
301a0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  d by [sqlite3_li
301b0 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
301c0 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a  IT_LENGTH]) or.*
301d0 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45  * [SQLITE_MAX_LE
301e0 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  NGTH]..** ^[SQLI
301f0 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
30200 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
30210 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
30220 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
30230 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d    ^[SQLITE_NOMEM
30240 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
30250 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
30260 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
30270 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
30280 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
30290 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
302a0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
302b0 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
302c0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
302d0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
302e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
302f0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
30300 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
30310 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
30320 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
30330 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
30340 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73  blob64(sqlite3_s
30350 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
30360 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f   void*, sqlite3_
30370 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20  uint64,.        
30380 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30390 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
303a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
303b0 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  d_double(sqlite3
303c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75  _stmt*, int, dou
303d0 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ble);.int sqlite
303e0 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
303f0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
30400 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
30410 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
30420 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
30430 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
30440 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
30450 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
30460 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  mt*, int);.int s
30470 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
30480 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
30490 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69  nt,const char*,i
304a0 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
304b0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
304c0 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
304d0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
304e0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
304f0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
30500 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
30510 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74  ind_text64(sqlit
30520 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
30530 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
30540 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20  te3_uint64,.    
30550 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30560 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69       void(*)(voi
30570 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68  d*), unsigned ch
30580 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e  ar encoding);.in
30590 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76  t sqlite3_bind_v
305a0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
305b0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73  t*, int, const s
305c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
305d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
305e0 5f 70 6f 69 6e 74 65 72 28 73 71 6c 69 74 65 33  _pointer(sqlite3
305f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 76 6f 69  _stmt*, int, voi
30600 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  d*, const char*,
30610 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
30620 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
30630 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
30640 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
30650 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74  nt n);.int sqlit
30660 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
30670 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
30680 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75  , int, sqlite3_u
30690 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int64);../*.** C
306a0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
306b0 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72  Of SQL Parameter
306c0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
306d0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
306e0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61  ^This routine ca
306f0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e  n be used to fin
30700 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
30710 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d  [SQL parameters]
30720 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72  .** in a [prepar
30730 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
30740 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61  SQL parameters a
30750 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65  re tokens of the
30760 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f  .** form "?", "?
30770 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24  NNN", ":AAA", "$
30780 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20  AAA", or "@AAA" 
30790 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a  that serve as.**
307a0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
307b0 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72  r values that ar
307c0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
307d0 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a  blob | bound].**
307e0 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
307f0 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69  rs at a later ti
30800 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  me..**.** ^(This
30810 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c   routine actuall
30820 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e  y returns the in
30830 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65  dex of the large
30840 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a  st (rightmost).*
30850 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72  * parameter. For
30860 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70   all forms excep
30870 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c  t ?NNN, this wil
30880 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20  l correspond to 
30890 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
308a0 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65   unique paramete
308b0 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65  rs.  If paramete
308c0 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66  rs of the ?NNN f
308d0 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a  orm are used,.**
308e0 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61   there may be ga
308f0 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29  ps in the list.)
30900 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
30910 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
30920 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
30930 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
30940 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
30950 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
30960 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
30970 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
30980 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
30990 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
309a0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
309b0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
309c0 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
309d0 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72  A Host Parameter
309e0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
309f0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
30a00 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
30a10 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
30a20 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  P,N) interface r
30a30 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61  eturns.** the na
30a40 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b  me of the N-th [
30a50 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69  SQL parameter] i
30a60 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
30a70 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
30a80 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72   ^(SQL parameter
30a90 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
30aa0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
30ab0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
30ac0 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d  A".** have a nam
30ad0 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73  e which is the s
30ae0 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20  tring "?NNN" or 
30af0 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
30b00 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65   or "$AAA".** re
30b10 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49  spectively..** I
30b20 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
30b30 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f  he initial ":" o
30b40 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20  r "$" or "@" or 
30b50 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64  "?".** is includ
30b60 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
30b70 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61  e name.)^.** ^Pa
30b80 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
30b90 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74  form "?" without
30ba0 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74   a following int
30bb0 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d  eger have no nam
30bc0 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66  e.** and are ref
30bd0 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d  erred to as "nam
30be0 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79  eless" or "anony
30bf0 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22  mous parameters"
30c00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
30c10 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
30c20 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
30c30 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
30c40 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20  * ^If the value 
30c50 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
30c60 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68  e or if the N-th
30c70 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
30c80 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20   nameless, then 
30c90 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
30ca0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
30cb0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
30cc0 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e  ways in UTF-8 en
30cd0 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
30ce0 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
30cf0 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
30d00 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
30d10 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
30d20 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
30d30 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
30d40 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20  repare16_v2()], 
30d50 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
30d60 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a  are16_v3()]..**.
30d70 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
30d80 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
30d90 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
30da0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
30db0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
30dc0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
30dd0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
30de0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
30df0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
30e00 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
30e10 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
30e20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
30e30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30e40 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
30e50 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
30e60 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44  n Name.** METHOD
30e70 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
30e80 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
30e90 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
30ea0 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
30eb0 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65   its name.  ^The
30ec0 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
30ed0 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
30ee0 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
30ef0 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
30f00 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
30f10 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
30f20 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
30f30 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65  ^A zero.** is re
30f40 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
30f50 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
30f60 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20  is found.  ^The 
30f70 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
30f80 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
30f90 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
30fa0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
30fb0 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
30fc0 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
30fd0 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
30fe0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
30ff0 36 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  6_v2()] or.** [s
31000 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
31010 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v3()]..**.** Se
31020 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
31030 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
31040 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
31050 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
31060 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
31070 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
31080 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
31090 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  name()]..*/.int 
310a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
310b0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
310c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
310d0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
310e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
310f0 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
31100 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
31110 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d  d Statement.** M
31120 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
31130 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72  tmt.**.** ^Contr
31140 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
31150 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
31160 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
31170 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a  does not reset.*
31180 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
31190 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
311a0 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61  ngs] on a [prepa
311b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
311c0 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75  ** ^Use this rou
311d0 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c  tine to reset al
311e0 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  l host parameter
311f0 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  s to NULL..*/.in
31200 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  t sqlite3_clear_
31210 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
31220 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
31230 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
31240 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
31250 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d   Result Set.** M
31260 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
31270 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  tmt.**.** ^Retur
31280 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
31290 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
312a0 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e  esult set return
312b0 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72  ed by the.** [pr
312c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
312d0 5d 2e 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74  ]. ^If this rout
312e0 69 6e 65 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ine returns 0, t
312f0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 0a 2a  hat means the .*
31300 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
31310 65 6d 65 6e 74 5d 20 72 65 74 75 72 6e 73 20 6e  ement] returns n
31320 6f 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  o data (for exam
31330 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
31340 2e 0a 2a 2a 20 5e 48 6f 77 65 76 65 72 2c 20 6a  ..** ^However, j
31350 75 73 74 20 62 65 63 61 75 73 65 20 74 68 69 73  ust because this
31360 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
31370 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62   a positive numb
31380 65 72 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d  er does not.** m
31390 65 61 6e 20 74 68 61 74 20 6f 6e 65 20 6f 72 20  ean that one or 
313a0 6d 6f 72 65 20 72 6f 77 73 20 6f 66 20 64 61 74  more rows of dat
313b0 61 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e  a will be return
313c0 65 64 2e 20 20 5e 41 20 53 45 4c 45 43 54 20 73  ed.  ^A SELECT s
313d0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c  tatement.** will
313e0 20 61 6c 77 61 79 73 20 68 61 76 65 20 61 20 70   always have a p
313f0 6f 73 69 74 69 76 65 20 73 71 6c 69 74 65 33 5f  ositive sqlite3_
31400 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 62  column_count() b
31410 75 74 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ut depending on 
31420 74 68 65 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61  the.** WHERE cla
31430 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  use constraints 
31440 61 6e 64 20 74 68 65 20 74 61 62 6c 65 20 63 6f  and the table co
31450 6e 74 65 6e 74 2c 20 69 74 20 6d 69 67 68 74 20  ntent, it might 
31460 72 65 74 75 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a  return no rows..
31470 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
31480 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
31490 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71  unt()].*/.int sq
314a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
314b0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
314c0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
314d0 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e  CAPI3REF: Column
314e0 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75   Names In A Resu
314f0 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44  lt Set.** METHOD
31500 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
31510 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
31520 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
31530 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
31540 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f   a particular co
31550 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72  lumn.** in the r
31560 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
31570 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
31580 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  t.  ^The sqlite3
31590 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
315a0 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
315b0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
315c0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
315d0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a  ed UTF-8 string.
315e0 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
315f0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72  olumn_name16() r
31600 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
31610 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
31620 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
31630 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69  string.  ^The fi
31640 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
31650 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
31660 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
31670 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
31680 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
31690 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ent. ^The second
316a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
316b0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  e.** column numb
316c0 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f  er.  ^The leftmo
316d0 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d  st column is num
316e0 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ber 0..**.** ^Th
316f0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
31700 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c  g pointer is val
31710 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20  id until either 
31720 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
31730 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64  atement].** is d
31740 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
31750 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
31760 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
31770 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
31780 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
31790 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
317a0 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
317b0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
317c0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
317d0 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
317e0 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
317f0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
31800 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
31810 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
31820 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
31830 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  olumn..**.** ^If
31840 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
31850 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
31860 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
31870 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
31880 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
31890 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
318a0 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
318b0 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
318c0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
318d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
318e0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
318f0 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
31900 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
31910 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
31920 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
31930 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
31940 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
31950 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
31960 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
31970 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
31980 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
31990 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
319a0 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
319b0 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
319c0 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
319d0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
319e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
319f0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
31a00 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
31a10 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
31a20 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
31a30 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
31a40 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
31a50 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
31a60 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
31a70 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  esult.** METHOD:
31a80 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
31a90 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
31aa0 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
31ab0 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
31ac0 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74   the database, t
31ad0 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62  able, and.** tab
31ae0 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69  le column that i
31af0 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20  s the origin of 
31b00 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73  a particular res
31b10 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a  ult column in.**
31b20 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
31b30 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ent..** ^The nam
31b40 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
31b50 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
31b60 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
31b70 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
31b80 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46  r a UTF-8 or UTF
31b90 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
31ba0 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
31bb0 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
31bc0 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
31bd0 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
31be0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
31bf0 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
31c00 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
31c10 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
31c20 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
31c30 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  e..** ^The retur
31c40 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
31c50 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70  lid until the [p
31c60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31c70 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a  t] is destroyed.
31c80 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
31c90 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
31ca0 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
31cb0 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
31cc0 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
31cd0 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
31ce0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
31cf0 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
31d00 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
31d10 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  * or until the s
31d20 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
31d30 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
31d40 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
31d50 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
31d60 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20  *.** ^The names 
31d70 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
31d80 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
31d90 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
31da0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
31db0 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
31dc0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
31dd0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
31de0 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
31df0 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
31e00 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54  tatement]..** ^T
31e10 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
31e20 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
31e30 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
31e40 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65  result column re
31e50 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65  turned by.** the
31e60 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72   statement, wher
31e70 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
31e80 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
31e90 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  ent..** ^The lef
31ea0 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  t-most column is
31eb0 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68   column 0 for th
31ec0 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
31ed0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20  .** ^If the Nth 
31ee0 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
31ef0 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
31f00 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
31f10 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79  n or.** subquery
31f20 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
31f30 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
31f40 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
31f50 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a  nctions return.*
31f60 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20  * NULL.  ^These 
31f70 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c  routine might al
31f80 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69  so return NULL i
31f90 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
31fa0 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f  ation error.** o
31fb0 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69  ccurs.  ^Otherwi
31fc0 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
31fd0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
31fe0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
31ff0 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20  e, table,.** or 
32000 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
32010 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  y result column 
32020 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
32030 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69  om..**.** ^As wi
32040 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
32050 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
32060 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20  whose names end 
32070 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e  with "16" return
32080 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  .** UTF-16 encod
32090 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74  ed strings and t
320a0 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f  he other functio
320b0 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e  ns return UTF-8.
320c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50  .**.** ^These AP
320d0 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  Is are only avai
320e0 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
320f0 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
32100 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
32110 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
32120 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d  UMN_METADATA] C-
32130 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
32140 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  bol..**.** If tw
32150 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
32160 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
32170 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
32180 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
32190 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
321a0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
321b0 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
321c0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
321d0 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
321e0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
321f0 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
32200 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
32210 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c   or more.** [sql
32220 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
32230 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75  base_name | colu
32240 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
32250 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74  rfaces].** for t
32260 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  he same [prepare
32270 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
32280 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a   result column.*
32290 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  * at the same ti
322a0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
322b0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
322c0 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  d..*/.const char
322d0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
322e0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73  _database_name(s
322f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
32300 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
32310 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
32320 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71  tabase_name16(sq
32330 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
32340 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
32350 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
32360 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  le_name(sqlite3_
32370 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
32380 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
32390 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
323a0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
323b0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
323c0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
323d0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73  mn_origin_name(s
323e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
323f0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
32400 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
32410 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  igin_name16(sqli
32420 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
32430 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32440 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79   Declared Dataty
32450 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65  pe Of A Query Re
32460 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  sult.** METHOD: 
32470 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
32480 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70  ** ^(The first p
32490 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
324a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
324b0 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  t]..** If this s
324c0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53  tatement is a [S
324d0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
324e0 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
324f0 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  umn of the.** re
32500 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
32510 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43  t of that [SELEC
32520 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  T] is a table co
32530 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
32540 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
32550 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
32560 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
32570 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
32580 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
32590 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74  d.)^  ^If the Nt
325a0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
325b0 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
325c0 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
325d0 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
325e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
325f0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
32600 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
32610 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
32620 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a  TF-8 encoded..**
32630 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
32640 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
32650 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
32660 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
32670 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
32680 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
32690 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
326a0 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
326b0 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
326c0 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
326d0 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
326e0 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
326f0 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
32700 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
32710 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
32720 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
32730 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
32740 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
32750 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
32760 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  (i==0).)^.**.** 
32770 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e  ^SQLite uses dyn
32780 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
32790 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20  ping.  ^So just 
327a0 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
327b0 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
327c0 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
327d0 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
327e0 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
327f0 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
32800 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
32810 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
32820 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
32830 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
32840 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
32850 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
32860 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
32870 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f  ^Type.** is asso
32880 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
32890 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
328a0 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
328b0 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
328c0 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
328d0 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ues..*/.const ch
328e0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
328f0 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
32900 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
32910 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
32920 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
32930 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
32940 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
32950 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
32960 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
32970 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ment.** METHOD: 
32980 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
32990 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70  ** After a [prep
329a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
329b0 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
329c0 64 20 75 73 69 6e 67 20 61 6e 79 20 6f 66 0a 2a  d using any of.*
329d0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
329e0 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
329f0 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
32a00 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
32a10 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 6f  re16_v2()],.** o
32a20 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
32a30 72 65 31 36 5f 76 33 28 29 5d 20 6f 72 20 6f 6e  re16_v3()] or on
32a40 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a  e of the legacy.
32a50 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
32a60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
32a70 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
32a80 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73  epare16()], this
32a90 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73   function.** mus
32aa0 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20  t be called one 
32ab0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
32ac0 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74   evaluate the st
32ad0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  atement..**.** T
32ae0 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
32af0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
32b00 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
32b10 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
32b20 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
32b30 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
32b40 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
32b50 20 74 68 65 20 6e 65 77 65 72 20 22 76 58 22 20   the newer "vX" 
32b60 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 5b 73  interfaces.** [s
32b70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
32b80 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70  3()], [sqlite3_p
32b90 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
32ba0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
32bb0 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v3()],.** [sqli
32bc0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
32bd0 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72  ()] or the older
32be0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
32bf0 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
32c00 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
32c10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
32c20 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
32c30 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 58 22   the.** new "vX"
32c40 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
32c50 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
32c60 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
32c70 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
32c80 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
32c90 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
32ca0 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
32cb0 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69  ^In the legacy i
32cc0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
32cd0 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
32ce0 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
32cf0 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_BUSY],.** [SQL
32d00 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
32d10 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
32d20 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
32d30 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
32d40 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69  ^With the "v2" i
32d50 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
32d60 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
32d70 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
32d80 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
32d90 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
32da0 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
32db0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  l..**.** ^[SQLIT
32dc0 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68  E_BUSY] means th
32dd0 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
32de0 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c  engine was unabl
32df0 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65  e to acquire the
32e00 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63  .** database loc
32e10 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64  ks it needs to d
32e20 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20  o its job.  ^If 
32e30 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
32e40 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f   a [COMMIT].** o
32e50 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
32e60 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
32e70 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
32e80 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
32e90 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
32ea0 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
32eb0 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f  ent is not a [CO
32ec0 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73  MMIT] and occurs
32ed0 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78   within an.** ex
32ee0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
32ef0 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
32f00 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
32f10 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
32f20 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
32f30 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
32f40 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61  _DONE] means tha
32f50 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
32f60 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
32f70 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73  cuting.** succes
32f80 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33  sfully.  sqlite3
32f90 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
32fa0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
32fb0 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75  in on this virtu
32fc0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69  al.** machine wi
32fd0 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c  thout first call
32fe0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
32ff0 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  et()] to reset t
33000 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  he virtual.** ma
33010 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74  chine back to it
33020 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e  s initial state.
33030 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53  .**.** ^If the S
33040 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  QL statement bei
33050 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75  ng executed retu
33060 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68  rns any data, th
33070 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a  en [SQLITE_ROW].
33080 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65  ** is returned e
33090 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72  ach time a new r
330a0 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65  ow of data is re
330b0 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69  ady for processi
330c0 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ng by the.** cal
330d0 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ler. The values 
330e0 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20  may be accessed 
330f0 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d  using the [colum
33100 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
33110 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
33120 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
33130 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
33140 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
33150 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e  of data..**.** ^
33160 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d  [SQLITE_ERROR] m
33170 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d  eans that a run-
33180 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68  time error (such
33190 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   as a constraint
331a0 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68  .** violation) h
331b0 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71  as occurred.  sq
331c0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
331d0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
331e0 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68  d again on.** th
331f0 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72  e VM. More infor
33200 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f  mation may be fo
33210 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  und by calling [
33220 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
33230 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
33240 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
33250 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
33260 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f  c error code (fo
33270 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53  r example,.** [S
33280 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
33290 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
332a0 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
332b0 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
332c0 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
332d0 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
332e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
332f0 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
33300 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33310 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22  ].  ^In the "v2"
33320 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74   interface,.** t
33330 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
33340 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
33350 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
33360 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
33370 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ()..**.** [SQLIT
33380 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20  E_MISUSE] means 
33390 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f  that the this ro
333a0 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64  utine was called
333b0 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79   inappropriately
333c0 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20  ..** Perhaps it 
333d0 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20  was called on a 
333e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
333f0 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a  ent] that has.**
33400 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73   already been [s
33410 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
33420 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20  | finalized] or 
33430 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a  on one that had.
33440 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ** previously re
33450 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45  turned [SQLITE_E
33460 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45  RROR] or [SQLITE
33470 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63  _DONE].  Or it c
33480 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63  ould.** be the c
33490 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d  ase that the sam
334a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
334b0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75  ction is being u
334c0 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a  sed by two or.**
334d0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74   more threads at
334e0 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74   the same moment
334f0 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
33500 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73  For all versions
33510 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f   of SQLite up to
33520 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33   and including 3
33530 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20  .6.23.1, a call 
33540 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  to.** [sqlite3_r
33550 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75  eset()] was requ
33560 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ired after sqlit
33570 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e  e3_step() return
33580 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f  ed anything.** o
33590 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
335a0 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e  E_ROW] before an
335b0 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  y subsequent inv
335c0 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71  ocation of.** sq
335d0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46  lite3_step().  F
335e0 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20  ailure to reset 
335f0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
33600 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a  tement using .**
33610 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
33620 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20  )] would result 
33630 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  in an [SQLITE_MI
33640 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f  SUSE] return fro
33650 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  m.** sqlite3_ste
33660 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20  p().  But after 
33670 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e  [version 3.6.23.
33680 31 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  1] ([dateof:3.6.
33690 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65  23.1],.** sqlite
336a0 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a  3_step() began.*
336b0 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * calling [sqlit
336c0 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f  e3_reset()] auto
336d0 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69  matically in thi
336e0 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72  s circumstance r
336f0 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65  ather.** than re
33700 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
33710 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69  MISUSE].  This i
33720 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64  s not considered
33730 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79   a compatibility
33740 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73  .** break becaus
33750 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f  e any applicatio
33760 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65  n that ever rece
33770 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d  ives an SQLITE_M
33780 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69  ISUSE error.** i
33790 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69  s broken by defi
337a0 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51  nition.  The [SQ
337b0 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45  LITE_OMIT_AUTORE
337c0 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  SET] compile-tim
337d0 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20  e option.** can 
337e0 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f  be used to resto
337f0 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  re the legacy be
33800 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  havior..**.** <b
33810 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
33820 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74   Alert:</b> In t
33830 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
33840 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ace, the sqlite3
33850 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61  _step().** API a
33860 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
33870 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
33880 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  de, [SQLITE_ERRO
33890 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
338a0 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72  y.** error other
338b0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
338c0 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  SY] and [SQLITE_
338d0 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
338e0 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  st call.** [sqli
338f0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
33900 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
33910 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
33920 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
33930 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72  .** specific [er
33940 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
33950 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
33960 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
33970 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
33980 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
33990 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
339a0 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
339b0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
339c0 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
339d0 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
339e0 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
339f0 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
33a00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
33a10 65 5f 76 33 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v3()] or [sqli
33a20 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
33a30 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
33a40 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
33a50 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
33a60 70 61 72 65 31 36 5f 76 33 28 29 5d 20 69 6e 73  pare16_v3()] ins
33a70 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
33a80 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
33a90 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
33aa0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
33ab0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
33ac0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
33ad0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
33ae0 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
33af0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
33b00 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
33b10 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
33b20 74 68 65 20 22 76 58 22 20 69 6e 74 65 72 66 61  the "vX" interfa
33b30 63 65 73 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ces is recommend
33b40 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
33b50 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
33b60 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
33b70 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
33b80 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
33b90 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45  result set.** ME
33ba0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
33bb0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
33bc0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
33bd0 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
33be0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
33bf0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
33c00 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f  he.** current ro
33c10 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
33c20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64  set of [prepared
33c30 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
33c40 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73  * ^If prepared s
33c50 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20  tatement P does 
33c60 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73  not have results
33c70 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e   ready to return
33c80 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74  .** (via calls t
33c90 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
33ca0 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69  olumn_int | sqli
33cb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20  te3_column_*()] 
33cc0 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
33cd0 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64  ) then sqlite3_d
33ce0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74  ata_count(P) ret
33cf0 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  urns 0..** ^The 
33d00 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
33d10 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c  nt(P) routine al
33d20 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  so returns 0 if 
33d30 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  P is a NULL poin
33d40 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ter..** ^The sql
33d50 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
33d60 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  P) routine retur
33d70 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76  ns 0 if the prev
33d80 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  ious call to.** 
33d90 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
33da0 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  ) returned [SQLI
33db0 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20  TE_DONE].  ^The 
33dc0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
33dd0 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65  nt(P).** will re
33de0 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66  turn non-zero if
33df0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
33e00 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  o [sqlite3_step]
33e10 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  (P) returned.** 
33e20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78  [SQLITE_ROW], ex
33e30 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65  cept in the case
33e40 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20   of the [PRAGMA 
33e50 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75  incremental_vacu
33e60 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20  um].** where it 
33e70 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a  always returns z
33e80 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73  ero since each s
33e90 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74  tep of that mult
33ea0 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61  i-step.** pragma
33eb0 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d   returns 0 colum
33ec0 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ns of data..**.*
33ed0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
33ee0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
33ef0 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  t()].*/.int sqli
33f00 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73  te3_data_count(s
33f10 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
33f20 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
33f30 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61  3REF: Fundamenta
33f40 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b  l Datatypes.** K
33f50 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
33f60 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65  TEXT.**.** ^(Eve
33f70 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69  ry value in SQLi
33f80 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69  te has one of fi
33f90 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64  ve fundamental d
33fa0 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20  atatypes:.**.** 
33fb0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  <ul>.** <li> 64-
33fc0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
33fd0 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  er.** <li> 64-bi
33fe0 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20  t IEEE floating 
33ff0 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20  point number.** 
34000 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c  <li> string.** <
34010 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e  li> BLOB.** <li>
34020 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e   NULL.** </ul>)^
34030 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
34040 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
34050 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
34060 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
34070 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
34080 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
34090 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
340a0 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
340b0 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
340c0 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
340d0 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
340e0 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
340f0 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
34100 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
34110 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
34120 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
34130 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20  e SQLITE3_TEXT, 
34140 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45  not.** SQLITE_TE
34150 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  XT..*/.#define S
34160 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31  QLITE_INTEGER  1
34170 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
34180 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69  FLOAT    2.#defi
34190 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20  ne SQLITE_BLOB  
341a0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
341b0 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23  ITE_NULL     5.#
341c0 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  ifdef SQLITE_TEX
341d0 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  T.# undef SQLITE
341e0 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65  _TEXT.#else.# de
341f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54  fine SQLITE_TEXT
34200 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64       3.#endif.#d
34210 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45  efine SQLITE3_TE
34220 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20  XT     3../*.** 
34230 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
34240 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
34250 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  uery.** KEYWORDS
34260 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  : {column access
34270 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d   functions}.** M
34280 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
34290 74 6d 74 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 6d  tmt.**.** <b>Sum
342a0 6d 61 72 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c  mary:</b>.** <bl
342b0 6f 63 6b 71 75 6f 74 65 3e 3c 74 61 62 6c 65 20  ockquote><table 
342c0 62 6f 72 64 65 72 3d 30 20 63 65 6c 6c 70 61 64  border=0 cellpad
342d0 64 69 6e 67 3d 30 20 63 65 6c 6c 73 70 61 63 69  ding=0 cellspaci
342e0 6e 67 3d 30 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ng=0>.** <tr><td
342f0 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ><b>sqlite3_colu
34300 6d 6e 5f 62 6c 6f 62 3c 2f 62 3e 3c 74 64 3e 26  mn_blob</b><td>&
34310 72 61 72 72 3b 3c 74 64 3e 42 4c 4f 42 20 72 65  rarr;<td>BLOB re
34320 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  sult.** <tr><td>
34330 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
34340 6e 5f 64 6f 75 62 6c 65 3c 2f 62 3e 3c 74 64 3e  n_double</b><td>
34350 26 72 61 72 72 3b 3c 74 64 3e 52 45 41 4c 20 72  &rarr;<td>REAL r
34360 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  esult.** <tr><td
34370 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ><b>sqlite3_colu
34380 6d 6e 5f 69 6e 74 3c 2f 62 3e 3c 74 64 3e 26 72  mn_int</b><td>&r
34390 61 72 72 3b 3c 74 64 3e 33 32 2d 62 69 74 20 49  arr;<td>32-bit I
343a0 4e 54 45 47 45 52 20 72 65 73 75 6c 74 0a 2a 2a  NTEGER result.**
343b0 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
343c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
343d0 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
343e0 64 3e 36 34 2d 62 69 74 20 49 4e 54 45 47 45 52  d>64-bit INTEGER
343f0 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c   result.** <tr><
34400 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
34410 6c 75 6d 6e 5f 74 65 78 74 3c 2f 62 3e 3c 74 64  lumn_text</b><td
34420 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d 38  >&rarr;<td>UTF-8
34430 20 54 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20   TEXT result.** 
34440 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
34450 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
34460 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
34470 64 3e 55 54 46 2d 31 36 20 54 45 58 54 20 72 65  d>UTF-16 TEXT re
34480 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  sult.** <tr><td>
34490 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
344a0 6e 5f 76 61 6c 75 65 3c 2f 62 3e 3c 74 64 3e 26  n_value</b><td>&
344b0 72 61 72 72 3b 3c 74 64 3e 54 68 65 20 72 65 73  rarr;<td>The res
344c0 75 6c 74 20 61 73 20 61 6e 20 0a 2a 2a 20 5b 73  ult as an .** [s
344d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7c 75 6e 70  qlite3_value|unp
344e0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
344f0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a  _value] object..
34500 2a 2a 20 3c 74 72 3e 3c 74 64 3e 26 6e 62 73 70  ** <tr><td>&nbsp
34510 3b 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26  ;<td>&nbsp;<td>&
34520 6e 62 73 70 3b 0a 2a 2a 20 3c 74 72 3e 3c 74 64  nbsp;.** <tr><td
34530 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ><b>sqlite3_colu
34540 6d 6e 5f 62 79 74 65 73 3c 2f 62 3e 3c 74 64 3e  mn_bytes</b><td>
34550 26 72 61 72 72 3b 3c 74 64 3e 53 69 7a 65 20 6f  &rarr;<td>Size o
34560 66 20 61 20 42 4c 4f 42 0a 2a 2a 20 6f 72 20 61  f a BLOB.** or a
34570 20 55 54 46 2d 38 20 54 45 58 54 20 72 65 73 75   UTF-8 TEXT resu
34580 6c 74 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c  lt in bytes.** <
34590 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
345a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
345b0 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 2f 62 3e  &nbsp;&nbsp;</b>
345c0 0a 2a 2a 20 3c 74 64 3e 26 72 61 72 72 3b 26 6e  .** <td>&rarr;&n
345d0 62 73 70 3b 26 6e 62 73 70 3b 3c 74 64 3e 53 69  bsp;&nbsp;<td>Si
345e0 7a 65 20 6f 66 20 55 54 46 2d 31 36 0a 2a 2a 20  ze of UTF-16.** 
345f0 54 45 58 54 20 69 6e 20 62 79 74 65 73 0a 2a 2a  TEXT in bytes.**
34600 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
34610 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 3c  te3_column_type<
34620 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
34630 3e 44 65 66 61 75 6c 74 0a 2a 2a 20 64 61 74 61  >Default.** data
34640 74 79 70 65 20 6f 66 20 74 68 65 20 72 65 73 75  type of the resu
34650 6c 74 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 3c 2f  lt.** </table></
34660 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
34670 2a 20 3c 62 3e 44 65 74 61 69 6c 73 3a 3c 2f 62  * <b>Details:</b
34680 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  >.**.** ^These r
34690 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69  outines return i
346a0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
346b0 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
346c0 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
346d0 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66  ** result row of
346e0 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65   a query.  ^In e
346f0 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69  very case the fi
34700 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
34710 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
34720 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
34730 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
34740 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64   being evaluated
34750 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
34760 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tmt*].** that wa
34770 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
34780 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
34790 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
347a0 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a   its variants).*
347b0 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  * and the second
347c0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
347d0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
347e0 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69  lumn for which i
347f0 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68  nformation.** sh
34800 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
34810 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  . ^The leftmost 
34820 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
34830 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65  sult set has the
34840 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68   index 0..** ^Th
34850 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
34860 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
34870 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  t can be determi
34880 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
34890 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
348a0 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  nt()]..**.** If 
348b0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
348c0 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65  t does not curre
348d0 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20  ntly point to a 
348e0 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66  valid row, or if
348f0 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69   the.** column i
34900 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
34910 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74  ange, the result
34920 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
34930 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
34940 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c   may only be cal
34950 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73  led when the mos
34960 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
34970 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
34980 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
34990 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61  d [SQLITE_ROW] a
349a0 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73  nd neither.** [s
349b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
349c0 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  nor [sqlite3_fin
349d0 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65  alize()] have be
349e0 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71  en called subseq
349f0 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
34a00 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
34a10 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
34a20 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
34a30 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
34a40 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
34a50 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
34a60 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
34a70 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
34a80 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
34a90 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
34aa0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
34ab0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
34ac0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
34ad0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
34ae0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
34af0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
34b00 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
34b10 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
34b20 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
34b30 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
34b40 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
34b50 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
34b60 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
34b70 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
34b80 73 69 78 20 69 6e 74 65 72 66 61 63 65 73 20 28  six interfaces (
34b90 5f 62 6c 6f 62 2c 20 5f 64 6f 75 62 6c 65 2c 20  _blob, _double, 
34ba0 5f 69 6e 74 2c 20 5f 69 6e 74 36 34 2c 20 5f 74  _int, _int64, _t
34bb0 65 78 74 2c 20 61 6e 64 20 5f 74 65 78 74 31 36  ext, and _text16
34bc0 29 0a 2a 2a 20 65 61 63 68 20 72 65 74 75 72 6e  ).** each return
34bd0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61 20   the value of a 
34be0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e  result column in
34bf0 20 61 20 73 70 65 63 69 66 69 63 20 64 61 74 61   a specific data
34c00 20 66 6f 72 6d 61 74 2e 20 20 49 66 0a 2a 2a 20   format.  If.** 
34c10 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
34c20 6e 20 69 73 20 6e 6f 74 20 69 6e 69 74 69 61 6c  n is not initial
34c30 6c 79 20 69 6e 20 74 68 65 20 72 65 71 75 65 73  ly in the reques
34c40 74 65 64 20 66 6f 72 6d 61 74 20 28 66 6f 72 20  ted format (for 
34c50 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 66 20 74  example,.** if t
34c60 68 65 20 71 75 65 72 79 20 72 65 74 75 72 6e 73  he query returns
34c70 20 61 6e 20 69 6e 74 65 67 65 72 20 62 75 74 20   an integer but 
34c80 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
34c90 6d 6e 5f 74 65 78 74 28 29 20 69 6e 74 65 72 66  mn_text() interf
34ca0 61 63 65 0a 2a 2a 20 69 73 20 75 73 65 64 20 74  ace.** is used t
34cb0 6f 20 65 78 74 72 61 63 74 20 74 68 65 20 76 61  o extract the va
34cc0 6c 75 65 29 20 74 68 65 6e 20 61 6e 20 61 75 74  lue) then an aut
34cd0 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e 76  omatic type conv
34ce0 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72  ersion is perfor
34cf0 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  med..**.** ^The 
34d00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
34d10 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
34d20 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51  turns the.** [SQ
34d30 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
34d40 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
34d50 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
34d60 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
34d70 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
34d80 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
34d90 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
34da0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
34db0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
34dc0 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
34dd0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
34de0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
34df0 4c 4c 5d 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75  LL]..** The retu
34e00 72 6e 20 76 61 6c 75 65 20 6f 66 20 73 71 6c 69  rn value of sqli
34e10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
34e20 29 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ) can be used to
34e30 20 64 65 63 69 64 65 20 77 68 69 63 68 0a 2a 2a   decide which.**
34e40 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 73 69   of the first si
34e50 78 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75  x interface shou
34e60 6c 64 20 62 65 20 75 73 65 64 20 74 6f 20 65 78  ld be used to ex
34e70 74 72 61 63 74 20 74 68 65 20 63 6f 6c 75 6d 6e  tract the column
34e80 20 76 61 6c 75 65 2e 0a 2a 2a 20 54 68 65 20 76   value..** The v
34e90 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
34ea0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34eb0 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
34ec0 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 0a  eaningful if no.
34ed0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 20 74 79 70  ** automatic typ
34ee0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  e conversions ha
34ef0 76 65 20 6f 63 63 75 72 72 65 64 20 66 6f 72 20  ve occurred for 
34f00 74 68 65 20 76 61 6c 75 65 20 69 6e 20 71 75 65  the value in que
34f10 73 74 69 6f 6e 2e 20 20 0a 2a 2a 20 41 66 74 65  stion.  .** Afte
34f20 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  r a type convers
34f30 69 6f 6e 2c 20 74 68 65 20 72 65 73 75 6c 74 20  ion, the result 
34f40 6f 66 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  of calling sqlit
34f50 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
34f60 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
34f70 2c 20 74 68 6f 75 67 68 20 68 61 72 6d 6c 65 73  , though harmles
34f80 73 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  s.  Future.** ve
34f90 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
34fa0 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
34fb0 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
34fc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
34fd0 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
34fe0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
34ff0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72  ..**.** If the r
35000 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
35010 6f 72 20 61 20 54 45 58 54 20 73 74 72 69 6e 67  or a TEXT string
35020 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
35030 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
35040 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
35050 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
35060 20 69 6e 74 65 72 66 61 63 65 73 20 63 61 6e 20   interfaces can 
35070 62 65 20 75 73 65 64 20 74 6f 20 64 65 74 65 72  be used to deter
35080 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 0a 2a 2a  mine the size.**
35090 20 6f 66 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   of that BLOB or
350a0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
350b0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
350c0 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
350d0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
350e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
350f0 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
35100 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
35110 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
35120 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
35130 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
35140 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
35150 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
35160 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
35170 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
35180 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
35190 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
351a0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
351b0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
351c0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
351d0 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
351e0 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
351f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
35200 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
35210 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
35220 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
35230 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
35240 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
35250 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
35260 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
35270 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
35280 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
35290 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
352a0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72  column_bytes() r
352b0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
352c0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
352d0 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
352e0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65  TF-16 string the
352f0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
35300 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a  lumn_bytes16().*
35310 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
35320 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
35330 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
35340 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
35350 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
35360 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
35370 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
35380 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
35390 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
353a0 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31   string to UTF-1
353b0 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  6 and then retur
353c0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
353d0 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
353e0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
353f0 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
35400 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
35410 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a  _bytes16() uses.
35420 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
35430 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
35440 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
35450 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
35460 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
35470 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
35480 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
35490 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
354a0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
354b0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
354c0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74  mn_bytes16() ret
354d0 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
354e0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
354f0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
35500 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
35510 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  ] and .** [sqlit
35520 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
35530 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c  6()] do not incl
35540 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
35550 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20  minators at the 
35560 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
35570 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72  ring.  ^For clar
35580 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20  ity: the values 
35590 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
355a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
355b0 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c  ytes()] and [sql
355c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
355d0 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e  s16()] are the n
355e0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
355f0 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
35600 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
35610 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
35620 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65  *.** ^Strings re
35630 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
35640 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
35650 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
35660 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
35670 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
35680 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
35690 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
356a0 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20   ^The return.** 
356b0 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
356c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
356d0 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
356e0 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c  th BLOB is a NUL
356f0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
35700 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e   <b>Warning:</b>
35710 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74   ^The object ret
35720 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
35730 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
35740 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
35750 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
35760 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
35770 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64  In a multithread
35780 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a  ed environment,.
35790 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  ** an unprotecte
357a0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
357b0 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20  object may only 
357c0 62 65 20 75 73 65 64 20 73 61 66 65 6c 79 20 77  be used safely w
357d0 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
357e0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e  bind_value()] an
357f0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
35800 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49  t_value()]..** I
35810 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74  f the [unprotect
35820 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
35830 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
35840 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
35850 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
35860 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20   is used in any 
35870 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75  other way, inclu
35880 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  ding calls.** to
35890 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
358a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
358b0 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  t()], [sqlite3_v
358c0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
358d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
358e0 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65  ue_bytes()], the
358f0 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74   behavior is not
35900 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 20   threadsafe..** 
35910 48 65 6e 63 65 2c 20 74 68 65 20 73 71 6c 69 74  Hence, the sqlit
35920 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
35930 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  ) interface.** i
35940 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 6e 6c 79 20  s normally only 
35950 75 73 65 66 75 6c 20 77 69 74 68 69 6e 20 74 68  useful within th
35960 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
35970 20 6f 66 20 0a 2a 2a 20 5b 61 70 70 6c 69 63 61   of .** [applica
35980 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
35990 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 20 5b   functions] or [
359a0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2c  virtual tables],
359b0 20 6e 6f 74 20 77 69 74 68 69 6e 0a 2a 2a 20 74   not within.** t
359c0 6f 70 2d 6c 65 76 65 6c 20 61 70 70 6c 69 63 61  op-level applica
359d0 74 69 6f 6e 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a  tion code..**.**
359e0 20 54 68 65 20 74 68 65 73 65 20 72 6f 75 74 69   The these routi
359f0 6e 65 73 20 6d 61 79 20 61 74 74 65 6d 70 74 20  nes may attempt 
35a00 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 64  to convert the d
35a10 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 72  atatype of the r
35a20 65 73 75 6c 74 2e 0a 2a 2a 20 5e 46 6f 72 20 65  esult..** ^For e
35a30 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
35a40 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
35a50 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
35a60 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
35a70 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
35a80 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
35a90 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
35aa0 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65  internally to pe
35ab0 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e  rform the.** con
35ac0 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69  version automati
35ad0 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f  cally.  ^(The fo
35ae0 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
35af0 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
35b00 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72  sions.** that ar
35b10 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
35b20 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
35b30 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
35b40 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
35b50 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
35b60 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
35b70 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
35b80 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
35b90 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
35ba0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
35bb0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
35bc0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
35bd0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
35be0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
35bf0 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
35c00 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
35c10 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
35c20 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c   Result is a NUL
35c30 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
35c40 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
35c50 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
35c60 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e  d> Result is a N
35c70 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
35c80 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
35c90 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
35ca0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
35cb0 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f  m integer to flo
35cc0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  at.** <tr><td> I
35cd0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54  NTEGER  <td>   T
35ce0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
35cf0 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
35d00 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  he integer.** <t
35d10 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
35d20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
35d30 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45  td> Same as INTE
35d40 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  GER->TEXT.** <tr
35d50 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
35d60 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
35d70 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
35d80 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
35d90 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
35da0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
35db0 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
35dc0 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74   the float.** <t
35dd0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
35de0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
35df0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c  td> [CAST] to BL
35e00 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  OB.** <tr><td>  
35e10 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54  TEXT    <td> INT
35e20 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
35e30 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
35e40 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
35e50 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
35e60 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
35e70 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64   REAL.** <tr><td
35e80 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
35e90 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e    BLOB    <td> N
35ea0 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e  o change.** <tr>
35eb0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
35ec0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
35ed0 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
35ee0 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
35ef0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46   BLOB    <td>  F
35f00 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41  LOAT    <td> [CA
35f10 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c  ST] to REAL.** <
35f20 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
35f30 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
35f40 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
35f50 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
35f60 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
35f70 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
35f80 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  >)^.**.** Note t
35f90 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
35fa0 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
35fb0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
35fc0 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
35fd0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
35fe0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
35ff0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
36000 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
36010 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
36020 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
36030 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54  nvalidated..** T
36040 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
36050 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61  and pointer inva
36060 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lidations might 
36070 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
36080 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a  following cases:
36090 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
360a0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
360b0 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f  content is a BLO
360c0 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  B and sqlite3_co
360d0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a  lumn_text() or.*
360e0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
360f0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
36100 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72  s called.  A zer
36110 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67  o-terminator mig
36120 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20  ht.**      need 
36130 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74  to be added to t
36140 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a  he string.</li>.
36150 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
36160 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
36170 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71  TF-8 text and sq
36180 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
36190 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20  es16() or.**    
361a0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
361b0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
361c0 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
361d0 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
361e0 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
361f0 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  TF-16.</li>.** <
36200 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
36210 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
36220 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
36230 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
36240 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
36250 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
36260 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
36270 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
36280 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
36290 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f       to UTF-8.</
362a0 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
362b0 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20  ** ^Conversions 
362c0 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
362d0 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
362e0 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
362f0 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
36300 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
36310 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
36320 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
36330 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
36340 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
36350 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
36360 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73  inter references
36370 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
36380 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
36390 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
363a0 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
363b0 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
363c0 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
363d0 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
363e0 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
363f0 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
36400 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
36410 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
36420 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  lidated..**.** T
36430 68 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63 79  he safest policy
36440 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
36450 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
36460 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
36470 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
36480 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69  .** <ul>.**  <li
36490 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
364a0 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20  text() followed 
364b0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
364c0 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
364d0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
364e0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c  olumn_blob() fol
364f0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
36500 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
36510 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
36520 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
36530 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  16() followed by
36540 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36550 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a  bytes16()</li>.*
36560 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
36570 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f   other words, yo
36580 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71  u should call sq
36590 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
365a0 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t(),.** sqlite3_
365b0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f  column_blob(), o
365c0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
365d0 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20  _text16() first 
365e0 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73  to force the res
365f0 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ult.** into the 
36600 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20  desired format, 
36610 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69  then invoke sqli
36620 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
36630 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
36640 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
36650 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69  ) to find the si
36660 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ze of the result
36670 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61  .  Do not mix ca
36680 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  lls.** to sqlite
36690 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
366a0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
366b0 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61  n_blob() with ca
366c0 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
366d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
366e0 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d  (), and do not m
366f0 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ix calls to sqli
36700 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
36710 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c  6().** with call
36720 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
36730 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
36740 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73  ** ^The pointers
36750 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61   returned are va
36760 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65  lid until a type
36770 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
36780 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62  rs as.** describ
36790 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74  ed above, or unt
367a0 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  il [sqlite3_step
367b0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
367c0 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
367d0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
367e0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  ()] is called.  
367f0 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63  ^The memory spac
36800 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73  e used to hold s
36810 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c  trings.** and BL
36820 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74  OBs is freed aut
36830 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20  omatically.  Do 
36840 6e 6f 74 20 70 61 73 73 20 74 68 65 20 70 6f 69  not pass the poi
36850 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
36860 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
36870 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
36880 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
36890 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
368a0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
368b0 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ree()]..**.** ^(
368c0 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
368d0 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
368e0 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
368f0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
36900 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
36910 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
36920 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
36930 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
36940 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
36950 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
36960 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
36970 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
36980 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
36990 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
369a0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
369b0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
369c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
369d0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29  [SQLITE_NOMEM].)
369e0 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ^.*/.const void 
369f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
36a00 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
36a10 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
36a20 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
36a30 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
36a40 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
36a50 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
36a60 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
36a70 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
36a80 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
36a90 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
36aa0 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
36ab0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
36ac0 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
36ad0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
36ae0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
36af0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
36b00 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
36b10 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
36b20 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
36b30 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
36b40 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
36b50 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
36b60 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
36b70 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
36b80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
36b90 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
36ba0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
36bb0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
36bc0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
36bd0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
36be0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
36bf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
36c00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
36c10 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
36c20 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
36c30 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
36c40 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
36c50 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
36c60 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
36c70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
36c80 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
36c90 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
36ca0 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
36cb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
36cc0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
36cd0 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
36ce0 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
36cf0 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
36d00 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66   errors.** or if
36d10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
36d20 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61  s never been eva
36d30 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c  luated, then sql
36d40 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
36d50 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54  returns.** SQLIT
36d60 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d  E_OK.  ^If the m
36d70 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
36d80 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65  ation of stateme
36d90 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65  nt S failed, the
36da0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e  n.** sqlite3_fin
36db0 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73  alize(S) returns
36dc0 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
36dd0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
36de0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72  .** [extended er
36df0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
36e00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
36e10 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e  nalize(S) routin
36e20 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
36e30 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
36e40 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20  ing.** the life 
36e50 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72  cycle of [prepar
36e60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a  ed statement] S:
36e70 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65  .** before state
36e80 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65  ment S is ever e
36e90 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a  valuated, after.
36ea0 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ** one or more c
36eb0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
36ec0 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66  _reset()], or af
36ed0 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20  ter any call.** 
36ee0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
36ef0 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ()] regardless o
36f00 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
36f10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
36f20 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  as.** completed 
36f30 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  execution..**.**
36f40 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74   ^Invoking sqlit
36f50 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e  e3_finalize() on
36f60 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
36f70 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
36f80 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  -op..**.** The a
36f90 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
36fa0 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b  finalize every [
36fb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
36fc0 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nt] in order to 
36fd0 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63  avoid.** resourc
36fe0 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20  e leaks.  It is 
36ff0 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72  a grievous error
37000 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
37010 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75  tion to try to u
37020 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64  se.** a prepared
37030 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
37040 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
37050 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65  alized.  Any use
37060 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a   of a prepared.*
37070 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  * statement afte
37080 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
37090 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75  nalized can resu
370a0 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
370b0 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  and.** undesirab
370c0 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68  le behavior such
370d0 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e   as segfaults an
370e0 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f  d heap corruptio
370f0 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
37100 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
37110 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
37120 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37130 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
37140 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
37150 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ect.** METHOD: s
37160 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
37170 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
37180 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
37190 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
371a0 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
371b0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
371c0 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
371d0 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
371e0 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
371f0 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
37200 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
37210 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
37220 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
37230 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
37240 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
37250 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
37260 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
37270 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
37280 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
37290 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
372a0 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
372b0 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
372c0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
372d0 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
372e0 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
372f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
37300 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
37310 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
37320 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
37330 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
37340 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
37350 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
37360 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
37370 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
37380 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
37390 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
373a0 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
373b0 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
373c0 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
373d0 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
373e0 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
373f0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
37400 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
37410 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
37420 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
37430 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
37440 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
37450 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
37460 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
37470 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
37480 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
37490 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
374a0 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
374b0 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
374c0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
374d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
374e0 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
374f0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
37500 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
37510 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
37520 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
37530 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
37540 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
37550 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
37560 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
37570 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
37580 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
37590 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
375a0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
375b0 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
375c0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
375d0 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
375e0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
375f0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
37600 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
37610 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
37620 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
37630 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ons}.** METHOD: 
37640 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
37650 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28  hese functions (
37660 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
37670 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
37680 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
37690 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
376a0 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
376b0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
376c0 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
376d0 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
376e0 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
376f0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
37700 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
37710 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73  only differences
37720 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73   between.** thes
37730 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74  e routines are t
37740 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
37750 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a   expected for.**
37760 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
37770 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20  meter (the name 
37780 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
37790 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a  being created).*
377a0 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e  * and the presen
377b0 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66  ce or absence of
377c0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61   a destructor ca
377d0 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68  llback for.** th
377e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
377f0 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  ta pointer..**.*
37800 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
37810 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64  ameter is the [d
37820 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37830 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65  on] to which the
37840 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
37850 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e   is to be added.
37860 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61    ^If an applica
37870 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74  tion uses more t
37880 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
37890 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
378a0 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  hen application-
378b0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
378c0 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
378d0 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64  ded.** to each d
378e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
378f0 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  on separately..*
37900 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
37910 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
37920 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
37930 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
37940 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
37950 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  edefined.  ^The 
37960 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
37970 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
37980 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20   255 bytes in a 
37990 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65  UTF-8.** represe
379a0 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69  ntation, exclusi
379b0 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74  ve of the zero-t
379c0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74  erminator.  ^Not
379d0 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a  e that the name.
379e0 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  ** length limit 
379f0 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65  is in UTF-8 byte
37a00 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s, not character
37a10 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74  s nor UTF-16 byt
37a20 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74  es.  .** ^Any at
37a30 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
37a40 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
37a50 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
37a60 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
37a70 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
37a80 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
37a90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
37aa0 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67   parameter (nArg
37ab0 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  ).** is the numb
37ac0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
37ad0 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
37ae0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
37af0 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66  egate takes. ^If
37b00 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
37b10 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20  is -1, then the 
37b20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
37b30 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
37b40 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
37b50 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65   of arguments be
37b60 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20  tween 0 and the 
37b70 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20  limit.** set by 
37b80 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
37b90 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
37ba0 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49  NCTION_ARG]).  I
37bb0 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
37bc0 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73  arameter is less
37bd0 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
37be0 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65  ter than 127 the
37bf0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
37c00 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s.** undefined..
37c10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
37c20 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
37c30 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
37c40 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
37c50 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
37c60 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
37c70 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
37c80 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
37c90 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70  meters.  The app
37ca0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
37cb0 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74  set this paramet
37cc0 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45  er to.** [SQLITE
37cd0 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65  _UTF16LE] if the
37ce0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
37cf0 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
37d00 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61   .** [sqlite3_va
37d10 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20  lue_text16le()] 
37d20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20  on an input, or 
37d30 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
37d40 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   if the.** imple
37d50 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
37d60 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  s [sqlite3_value
37d70 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20  _text16be()] on 
37d80 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20  an input, or.** 
37d90 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69  [SQLITE_UTF16] i
37da0 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
37db0 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73  _text16()] is us
37dc0 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ed, or [SQLITE_U
37dd0 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73  TF8].** otherwis
37de0 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51  e.  ^The same SQ
37df0 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  L function may b
37e00 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c  e registered mul
37e10 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e  tiple times usin
37e20 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70  g.** different p
37e30 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
37e40 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69  codings, with di
37e50 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  fferent implemen
37e60 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65  tations for.** e
37e70 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ach encoding..**
37e80 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
37e90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
37ea0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
37eb0 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
37ec0 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
37ed0 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
37ee0 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
37ef0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
37f00 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
37f10 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  n..**.** ^The fo
37f20 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d  urth parameter m
37f30 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65  ay optionally be
37f40 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49   ORed with [SQLI
37f50 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
37f60 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74  ].** to signal t
37f70 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hat the function
37f80 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
37f90 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73  urn the same res
37fa0 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65  ult given.** the
37fb0 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74   same inputs wit
37fc0 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  hin a single SQL
37fd0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73   statement.  Mos
37fe0 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
37ff0 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69  are.** determini
38000 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74  stic.  The built
38010 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53  -in [random()] S
38020 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  QL function is a
38030 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a  n example of a.*
38040 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  * function that 
38050 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69  is not determini
38060 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74  stic.  The SQLit
38070 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20  e query planner 
38080 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65  is able to.** pe
38090 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c  rform additional
380a0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f   optimizations o
380b0 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20  n deterministic 
380c0 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73  functions, so us
380d0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  e.** of the [SQL
380e0 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
380f0 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d  C] flag is recom
38100 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73  mended where pos
38110 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  sible..**.** ^(T
38120 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
38130 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
38140 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
38150 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
38160 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
38170 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
38180 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
38190 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
381a0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
381b0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
381c0 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
381d0 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
381e0 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
381f0 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
38200 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
38210 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
38220 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
38230 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
38240 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
38250 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
38260 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
38270 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
38280 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
38290 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
382a0 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
382b0 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
382c0 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
382d0 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
382e0 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
382f0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
38300 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
38310 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
38320 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
38330 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
38340 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
38350 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
38360 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
38370 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
38380 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
38390 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
383a0 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
383b0 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
383c0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
383d0 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
383e0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
383f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
38400 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
38410 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
38420 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
38430 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
38440 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
38450 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
38460 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
38470 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
38480 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
38490 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
384a0 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
384b0 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
384c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
384d0 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
384e0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
384f0 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
38500 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
38510 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
38520 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
38530 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
38540 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
38550 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
38560 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
38570 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
38580 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
38590 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
385a0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
385b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
385c0 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
385d0 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
385e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
385f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
38600 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
38610 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
38620 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
38630 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
38640 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
38650 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
38660 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
38670 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
38680 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
38690 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
386a0 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
386b0 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
386c0 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
386d0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
386e0 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
386f0 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
38700 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
38710 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
38720 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
38730 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
38740 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
38750 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
38760 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
38770 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
38780 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
38790 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
387a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementati