/ Hex Artifact Content
Login

Artifact 7a0789ad7159a2c7995eef91c246e164aeb3aef8622bf66dacfe7dfd180cc0cb:


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 0a 2a 2a 0a  source tree..**.
10c0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
10d0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
10e0: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
10f0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1100: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
1110: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
1120: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
1130: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
1140: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
1150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1160: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
1170: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1180: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1190: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
11a0: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
11b0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
11c0: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
11d0: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
11e0: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
11f0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1200: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1210: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
1220: 65 72 73 69 6f 6e 20 73 71 6c 69 74 65 33 5f 73  ersion sqlite3_s
1230: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
1240: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
1250: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
1260: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
1270: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1280: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1290: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
12a0: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
12b0: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
12c0: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
12d0: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
12e0: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
12f0: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
1300: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
1310: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
1320: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
1330: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
1340: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
1350: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
1360: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
1370: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1380: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1390: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
13a0: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
13b0: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
13c0: 74 68 75 73 20 65 6e 73 75 72 65 20 74 68 61 74  thus ensure that
13d0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
13e0: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
13f0: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
1400: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
1410: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
1420: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1430: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
1440: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1450: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
1460: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
1470: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1480: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  mp(sqlite3_sourc
1490: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55  eid(),SQLITE_SOU
14a0: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a  RCE_ID)==0 );.**
14b0: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
14c0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
14d0: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53  on(),SQLITE_VERS
14e0: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f  ION)==0 );.** </
14f0: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1500: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1510: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1520: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1530: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
1540: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45  xt of [SQLITE_VE
1550: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e  RSION].** macro.
1560: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c    ^The sqlite3_l
1570: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
1580: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70  tion returns a p
1590: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
15a0: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
15b0: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
15c0: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
15d0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
15e0: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  on().** function
15f0: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
1600: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1610: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
1620: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
1630: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73  .** direct acces
1640: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73  s to string cons
1650: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
1660: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73   DLL.  ^The.** s
1670: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1680: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74  n_number() funct
1690: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ion returns an i
16a0: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a  nteger equal to.
16b0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
16c0: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68  ON_NUMBER].  ^Th
16d0: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  e sqlite3_source
16e0: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  id() function re
16f0: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  turns .** a poin
1700: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
1710: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76  constant whose v
1720: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65  alue is the same
1730: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c   as the .** [SQL
1740: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
1750: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1760: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  cro..**.** See a
1770: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
1780: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
1790: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
17a0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
17b0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
17c0: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
17d0: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
17e0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
17f0: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1800: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1810: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1820: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1830: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1840: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1850: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
1860: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
1870: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
1880: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1890: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
18a0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
18b0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
18c0: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
18d0: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
18e0: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
18f0: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1900: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1910: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1920: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1930: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1940: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1950: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1960: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1970: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1980: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1990: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
19a0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
19b0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
19c0: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
19d0: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
19e0: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
19f0: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1a00: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1a10: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1a20: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1a30: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1a40: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1a60: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1a70: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1a80: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1a90: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1aa0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1ab0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1ac0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1ad0: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1ae0: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1af0: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1b00: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1b10: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1b20: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1b30: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1b40: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1b50: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1b60: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1b70: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1b80: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1b90: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ba0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1bb0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1bc0: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1bd0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1be0: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1bf0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1c00: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1c10: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1c20: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1c30: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1c40: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1c50: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1c60: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c70: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1c80: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1c90: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1ca0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1cb0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1cc0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1cd0: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1ce0: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1cf0: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1d00: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1d10: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1d20: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1d30: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1d40: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1d50: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1d60: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1d70: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1d80: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d90: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1da0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1db0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1dc0: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1dd0: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1de0: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1df0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1e00: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1e10: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1e20: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1e30: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1e40: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1e50: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1e60: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1e70: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1e80: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1e90: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1ea0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1eb0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
1ec0: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
1ed0: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
1ee0: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
1ef0: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
1f00: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
1f10: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
1f20: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
1f30: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
1f40: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
1f50: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
1f60: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
1f70: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
1f80: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
1f90: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
1fa0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
1fb0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
1fc0: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
1fd0: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
1fe0: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
1ff0: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2000: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2010: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2020: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2030: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
2040: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
2050: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
2060: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
2070: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
2080: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
2090: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
20a0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
20b0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
20c0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
20d0: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
20e0: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
20f0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2100: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2110: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2120: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2130: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2140: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
2150: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
2160: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
2170: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
2180: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
2190: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
21a0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
21b0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
21c0: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
21d0: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
21e0: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
21f0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2200: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2210: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2220: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2230: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
2240: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
2250: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
2260: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
2270: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
2280: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
2290: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
22a0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
22b0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
22c0: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
22d0: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
22e0: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
22f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2300: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2310: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2320: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2330: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2340: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2350: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2360: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
2370: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
2380: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
2390: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
23a0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
23b0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
23c0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
23d0: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
23e0: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
23f0: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2400: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2410: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2420: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2430: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2440: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2450: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
2460: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
2470: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
2480: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
2490: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
24a0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
24b0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
24c0: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
24d0: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
24e0: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
24f0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2500: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2510: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2520: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2530: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2540: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2550: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
2560: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
2570: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
2580: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
2590: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
25a0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
25b0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
25c0: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
25d0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
25e0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
25f0: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2600: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2610: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2620: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2630: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2640: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2650: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
2660: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2670: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
2680: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
2690: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
26a0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
26b0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
26c0: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
26d0: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
26e0: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
26f0: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2700: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2710: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2720: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2730: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2740: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2750: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
2760: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
2770: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
2780: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
2790: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
27a0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
27b0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
27c0: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
27d0: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
27e0: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
27f0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2800: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2810: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2820: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2830: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2840: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2850: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
2860: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
2870: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
2880: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
2890: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
28a0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
28b0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
28c0: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
28d0: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
28e0: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
28f0: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2900: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2910: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2920: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2930: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2940: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2950: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2960: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45  ;.# ifdef SQLITE
2970: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20  _UINT64_TYPE.   
2980: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2990: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  UINT64_TYPE sqli
29a0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73  te_uint64;.# els
29b0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20  e  .    typedef 
29c0: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
29d0: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
29e0: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69  e_uint64;.# endi
29f0: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  f.#elif defined(
2a00: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2a10: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2a20: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2a30: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2a40: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2a50: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2a60: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2a70: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2a80: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2a90: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2aa0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2ab0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2ac0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2ad0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2ae0: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2af0: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2b00: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2b10: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2b20: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2b30: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2b40: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2b50: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2b60: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2b70: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2b80: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2b90: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2ba0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2bb0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2bc0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2bd0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2be0: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2bf0: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2c00: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2c10: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2c20: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2c30: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2c40: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2c50: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2c60: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2c70: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2c80: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2c90: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2ca0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2cb0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2cc0: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2cd0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2ce0: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2cf0: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2d00: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2d10: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2d20: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2d30: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2d40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d50: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2d60: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2d70: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2d80: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2d90: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2da0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2db0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2dc0: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2dd0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2de0: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2df0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2e00: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2e10: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2e20: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2e30: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2e40: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2e50: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2e60: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2e70: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2e80: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2e90: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2ea0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2eb0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
2ec0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
2ed0: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
2ee0: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
2ef0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2f00: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
2f10: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
2f20: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
2f30: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
2f40: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
2f50: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
2f60: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
2f70: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
2f80: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
2f90: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
2fa0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
2fb0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
2fc0: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
2fd0: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
2fe0: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
2ff0: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3000: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3010: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
3020: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3030: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3040: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3050: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
3060: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
3070: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
3080: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
3090: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
30a0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
30b0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
30c0: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
30d0: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
30e0: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
30f0: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3100: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3110: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3120: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3130: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3140: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3150: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
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 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
3180: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
3190: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
31a0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
31b0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
31c0: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
31d0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
31e0: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
31f0: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3200: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3210: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3220: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3230: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3240: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3250: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
3260: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
3270: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
3280: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
3290: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
32a0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
32b0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
32c0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
32d0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
32e0: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
32f0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3300: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3310: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3320: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3330: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3340: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3350: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
3360: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3370: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
3380: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
3390: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
33a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
33b0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
33c0: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
33d0: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
33e0: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
33f0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3400: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3410: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3420: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3430: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3440: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3450: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
3460: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
3470: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
3480: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
3490: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
34a0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
34b0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
34c0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
34d0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
34e0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
34f0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3500: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3510: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3520: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3530: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3540: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3550: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
3560: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
3570: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
3580: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
3590: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
35a0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
35b0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
35c0: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
35d0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
35e0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
35f0: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3600: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3610: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
3620: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
3630: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
3640: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
3650: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
3660: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
3670: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
3680: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
3690: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
36a0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
36b0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
36c0: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
36d0: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
36e0: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
36f0: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
3700: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
3710: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
3720: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3730: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
3740: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
3750: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
3760: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
3770: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
3780: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
3790: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
37a0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
37b0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
37c0: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
37d0: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
37e0: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
37f0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3800: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3810: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3820: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
3830: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3840: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
3850: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
3860: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
3870: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
3880: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
3890: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
38a0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
38b0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
38c0: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
38d0: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
38e0: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
38f0: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3900: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
3910: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
3920: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3930: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3940: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
3950: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3960: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3970: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3980: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3990: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
39a0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
39b0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
39c0: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
39d0: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
39e0: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
39f0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3a00: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
3a10: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3a20: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
3a30: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
3a40: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
3a50: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3a60: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3a70: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3a80: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3a90: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3aa0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3ab0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3ac0: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3ad0: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3ae0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3af0: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3b00: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3b10: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3b20: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3b30: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3b40: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3b50: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3b60: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3b70: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3b80: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3b90: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3ba0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3bb0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3bc0: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3bd0: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3be0: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3bf0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3c00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3c10: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3c20: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3c30: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3c40: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3c50: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3c60: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3c70: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3c80: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3c90: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3ca0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3cb0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3cc0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3cd0: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3ce0: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3cf0: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3d00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3d10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3d20: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3d30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3d40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3d50: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3d60: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3d70: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3d80: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3d90: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3da0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3db0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3dc0: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3dd0: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3de0: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3df0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3e00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3e10: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3e20: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3e30: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3e40: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3e50: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3e60: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3e70: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3e80: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3e90: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3ea0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3eb0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
3ec0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3ed0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
3ee0: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
3ef0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3f00: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3f10: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
3f20: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
3f30: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
3f40: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
3f50: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
3f60: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
3f70: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
3f80: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
3f90: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
3fa0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
3fb0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
3fc0: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
3fd0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
3fe0: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
3ff0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
4000: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4010: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
4020: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
4030: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
4040: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
4050: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
4060: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
4070: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
4080: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4090: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
40a0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
40b0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
40c0: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
40d0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
40e0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
40f0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4100: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4110: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4120: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4130: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
4140: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
4150: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
4160: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
4170: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
4180: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
4190: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
41a0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
41b0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
41c0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
41d0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41f0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4200: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4210: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4230: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4240: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4250: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
4260: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
4270: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
4280: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
4290: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42c0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
42d0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
42e0: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
42f0: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4310: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4320: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4330: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4340: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4350: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4360: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
4370: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
4380: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
4390: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
43a0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
43b0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
43c0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
43d0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
43e0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
43f0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4400: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4410: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4420: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4430: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4440: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4450: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
4460: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
4470: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
4480: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
4490: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
44a0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
44b0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
44c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
44d0: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
44e0: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72  /* Generic error
44f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4500: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4510: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4520: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4530: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4540: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4550: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
4560: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
4570: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4580: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
4590: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
45a0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
45b0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
45c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45d0: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
45e0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
45f0: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4600: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4610: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4620: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4630: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4640: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4650: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
4660: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
4670: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
4680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4690: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
46a0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
46b0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
46c0: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
46d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
46e0: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
46f0: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4700: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4710: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4720: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4730: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4740: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4750: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
4760: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
4770: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
4780: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
4790: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
47a0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
47b0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
47c0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
47d0: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
47e0: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
47f0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4800: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4810: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4820: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4830: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4840: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4850: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
4860: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
4870: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
4880: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
4890: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
48a0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
48b0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
48c0: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
48d0: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
48e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
48f0: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4900: 2a 20 4e 6f 74 20 75 73 65 64 20 2a 2f 0a 23 64  * Not used */.#d
4910: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
4920: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
4930: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
4940: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
4950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
4960: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
4970: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
4980: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
4990: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
49a0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
49b0: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
49c0: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
49d0: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
49e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
49f0: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
4a00: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
4a10: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
4a20: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
4a30: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
4a40: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
4a50: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
4a60: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
4a70: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
4a80: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
4a90: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
4aa0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4ab0: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
4ac0: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
4ad0: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
4ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4af0: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
4b00: 2f 2a 20 4e 6f 74 20 75 73 65 64 20 2a 2f 0a 23  /* Not used */.#
4b10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41  define SQLITE_RA
4b20: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f  NGE       25   /
4b30: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
4b40: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20  to sqlite3_bind 
4b50: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a  out of range */.
4b60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4b70: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20  OTADB      26   
4b80: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74  /* File opened t
4b90: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74  hat is not a dat
4ba0: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
4bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4bc0: 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a  ICE      27   /*
4bd0: 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66   Notifications f
4be0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4bf0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4c00: 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20  ITE_WARNING     
4c10: 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73  28   /* Warnings
4c20: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f   from sqlite3_lo
4c30: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  g() */.#define S
4c40: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4c50: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4c60: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4c70: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4c80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4c90: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4ca0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4cb0: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4cc0: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4cd0: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4ce0: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4cf0: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4d00: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4d10: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4d20: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4d30: 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a   definitions}.**
4d40: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
4d50: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
4d60: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
4d70: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
4d80: 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a   of 30 integer.*
4d90: 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  * [result codes]
4da0: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4db0: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4dc0: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
4dd0: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4de0: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
4df0: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
4e00: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
4e10: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
4e20: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
4e30: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
4e40: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
4e50: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4e60: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4e70: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4e80: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4e90: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 5b 64 61 74  rsion 3.3.8 [dat
4ea0: 65 6f 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20 61 6e  eof:3.3.8].** an
4eb0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
4ec0: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
4ed0: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
4ee0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
4ef0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4f00: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
4f10: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
4f20: 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20  These [extended 
4f30: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72  result codes] ar
4f40: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
4f50: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
4f60: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
4f70: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
4f80: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
4f90: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
4fa0: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20  t_codes()] API. 
4fb0: 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65   Or, the extende
4fc0: 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68  d code for.** th
4fd0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72  e most recent er
4fe0: 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69  ror can be obtai
4ff0: 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
5000: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
5010: 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64  rrcode()]..*/.#d
5020: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5030: 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  RR_READ         
5040: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5050: 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  RR | (1<<8)).#de
5060: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5070: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20  R_SHORT_READ    
5080: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5090: 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  R | (2<<8)).#def
50a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
50b0: 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  _WRITE          
50c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
50d0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
50e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
50f0: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  FSYNC           
5100: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5110: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
5120: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
5130: 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  IR_FSYNC        
5140: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5150: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5160: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52   SQLITE_IOERR_TR
5170: 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20  UNCATE          
5180: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5190: 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (6<<8)).#define 
51a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54  SQLITE_IOERR_FST
51b0: 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28  AT             (
51c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
51d0: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
51e0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f  QLITE_IOERR_UNLO
51f0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
5200: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38  QLITE_IOERR | (8
5210: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5220: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43  LITE_IOERR_RDLOC
5230: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
5240: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c  LITE_IOERR | (9<
5250: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5260: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
5270: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5280: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c  ITE_IOERR | (10<
5290: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
52a0: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
52b0: 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  D           (SQL
52c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c  ITE_IOERR | (11<
52d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
52e0: 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20  ITE_IOERR_NOMEM 
52f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5300: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c  ITE_IOERR | (12<
5310: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5320: 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53  ITE_IOERR_ACCESS
5330: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5340: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c  ITE_IOERR | (13<
5350: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5360: 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52  ITE_IOERR_CHECKR
5370: 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c  ESERVEDLOCK (SQL
5380: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c  ITE_IOERR | (14<
5390: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
53a0: 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20  ITE_IOERR_LOCK  
53b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
53c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c  ITE_IOERR | (15<
53d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
53e0: 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20  ITE_IOERR_CLOSE 
53f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5400: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c  ITE_IOERR | (16<
5410: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5420: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c  ITE_IOERR_DIR_CL
5430: 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c  OSE         (SQL
5440: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c  ITE_IOERR | (17<
5450: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5460: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45  ITE_IOERR_SHMOPE
5470: 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  N           (SQL
5480: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c  ITE_IOERR | (18<
5490: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
54a0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a  ITE_IOERR_SHMSIZ
54b0: 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  E           (SQL
54c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c  ITE_IOERR | (19<
54d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
54e0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43  ITE_IOERR_SHMLOC
54f0: 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  K           (SQL
5500: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c  ITE_IOERR | (20<
5510: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5520: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50  ITE_IOERR_SHMMAP
5530: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5540: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c  ITE_IOERR | (21<
5550: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5560: 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20  ITE_IOERR_SEEK  
5570: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5580: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c  ITE_IOERR | (22<
5590: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
55a0: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
55b0: 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c  _NOENT      (SQL
55c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c  ITE_IOERR | (23<
55d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
55e0: 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20  ITE_IOERR_MMAP  
55f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5600: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c  ITE_IOERR | (24<
5610: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5620: 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d  ITE_IOERR_GETTEM
5630: 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  PPATH       (SQL
5640: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c  ITE_IOERR | (25<
5650: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5660: 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41  ITE_IOERR_CONVPA
5670: 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  TH          (SQL
5680: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c  ITE_IOERR | (26<
5690: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56a0: 49 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20  ITE_IOERR_VNODE 
56b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
56c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c  ITE_IOERR | (27<
56d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56e0: 49 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20 20  ITE_IOERR_AUTH  
56f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5700: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c  ITE_IOERR | (28<
5710: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5720: 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45  ITE_LOCKED_SHARE
5730: 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c  DCACHE      (SQL
5740: 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31  ITE_LOCKED |  (1
5750: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5760: 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45  LITE_BUSY_RECOVE
5770: 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51  RY           (SQ
5780: 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28  LITE_BUSY   |  (
5790: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
57a0: 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53  QLITE_BUSY_SNAPS
57b0: 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28 53  HOT           (S
57c0: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20  QLITE_BUSY   |  
57d0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
57e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
57f0: 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 28  NOTEMPDIR      (
5800: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5810: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5820: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5830: 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20 20  N_ISDIR         
5840: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5850: 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  N | (2<<8)).#def
5860: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5870: 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20  PEN_FULLPATH    
5880: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
5890: 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  PEN | (3<<8)).#d
58a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
58b0: 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20  TOPEN_CONVPATH  
58c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
58d0: 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a  TOPEN | (4<<8)).
58e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
58f0: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20  ORRUPT_VTAB     
5900: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5910: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29  ORRUPT | (1<<8))
5920: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5930: 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52  READONLY_RECOVER
5940: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  Y       (SQLITE_
5950: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38  READONLY | (1<<8
5960: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5970: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c  E_READONLY_CANTL
5980: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  OCK       (SQLIT
5990: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c  E_READONLY | (2<
59a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
59b0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c  ITE_READONLY_ROL
59c0: 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c  LBACK       (SQL
59d0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
59e0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
59f0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44  QLITE_READONLY_D
5a00: 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28 53  BMOVED        (S
5a10: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5a20: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5a30: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f   SQLITE_ABORT_RO
5a40: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20  LLBACK          
5a50: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20  (SQLITE_ABORT | 
5a60: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5a70: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a80: 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 28  T_CHECK        (
5a90: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5aa0: 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  T | (1<<8)).#def
5ab0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5ac0: 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b  RAINT_COMMITHOOK
5ad0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5ae0: 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a  RAINT | (2<<8)).
5af0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5b00: 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47  ONSTRAINT_FOREIG
5b10: 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  NKEY   (SQLITE_C
5b20: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c  ONSTRAINT | (3<<
5b30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5b40: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55  TE_CONSTRAINT_FU
5b50: 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49  NCTION     (SQLI
5b60: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5b70: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5b80: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b90: 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28  T_NOTNULL      (
5ba0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5bb0: 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  T | (5<<8)).#def
5bc0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5bd0: 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59  RAINT_PRIMARYKEY
5be0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5bf0: 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a  RAINT | (6<<8)).
5c00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5c10: 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45  ONSTRAINT_TRIGGE
5c20: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5c30: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c  ONSTRAINT | (7<<
5c40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5c50: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e  TE_CONSTRAINT_UN
5c60: 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c 49  IQUE       (SQLI
5c70: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5c80: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (8<<8)).#define 
5c90: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5ca0: 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 28  T_VTAB         (
5cb0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5cc0: 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  T | (9<<8)).#def
5cd0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5ce0: 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20  RAINT_ROWID     
5cf0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5d00: 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a  RAINT |(10<<8)).
5d10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
5d20: 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41  OTICE_RECOVER_WA
5d30: 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e  L      (SQLITE_N
5d40: 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a  OTICE | (1<<8)).
5d50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
5d60: 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f  OTICE_RECOVER_RO
5d70: 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e  LLBACK (SQLITE_N
5d80: 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a  OTICE | (2<<8)).
5d90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57  #define SQLITE_W
5da0: 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58  ARNING_AUTOINDEX
5db0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57         (SQLITE_W
5dc0: 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29  ARNING | (1<<8))
5dd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5de0: 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 20 20  AUTH_USER       
5df0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5e00: 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23  AUTH | (1<<8)).#
5e10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
5e20: 5f 4c 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c  _LOAD_PERMANENTL
5e30: 59 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b  Y     (SQLITE_OK
5e40: 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a   | (1<<8))../*.*
5e50: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
5e60: 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20  s For File Open 
5e70: 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  Operations.**.**
5e80: 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65   These bit value
5e90: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
5ea0: 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a  or use in the.**
5eb0: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
5ec0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  o the [sqlite3_o
5ed0: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
5ee0: 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68  ace and.** in th
5ef0: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
5f00: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5f10: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
5f20: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d..*/.#define SQ
5f30: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
5f40: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
5f50: 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72  00001  /* Ok for
5f60: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5f70: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5f80: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
5f90: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
5fa0: 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72  00002  /* Ok for
5fb0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5fc0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5fd0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
5fe0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5ff0: 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72  00004  /* Ok for
6000: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6010: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6020: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
6030: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
6040: 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e  00008  /* VFS on
6050: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6060: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
6070: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
6080: 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00010  /* VFS on
6090: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
60a0: 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52  LITE_OPEN_AUTOPR
60b0: 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30  OXY        0x000
60c0: 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00020  /* VFS on
60d0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
60e0: 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20  LITE_OPEN_URI   
60f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6100: 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00040  /* Ok for
6110: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6120: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6130: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59  LITE_OPEN_MEMORY
6140: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6150: 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00080  /* Ok for
6160: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6170: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6180: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
6190: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
61a0: 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00100  /* VFS on
61b0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
61c0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
61d0: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
61e0: 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00200  /* VFS on
61f0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6200: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
6210: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
6220: 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00400  /* VFS on
6230: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6240: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
6250: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
6260: 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00800  /* VFS on
6270: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6280: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
6290: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
62a0: 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  01000  /* VFS on
62b0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
62c0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
62d0: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
62e0: 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  02000  /* VFS on
62f0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6300: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
6310: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
6320: 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  04000  /* VFS on
6330: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6340: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
6350: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  X          0x000
6360: 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  08000  /* Ok for
6370: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6380: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6390: 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
63a0: 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30  TEX        0x000
63b0: 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  10000  /* Ok for
63c0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
63d0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
63e0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
63f0: 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30  CACHE      0x000
6400: 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  20000  /* Ok for
6410: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6420: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6430: 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
6440: 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30  ECACHE     0x000
6450: 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  40000  /* Ok for
6460: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6470: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6480: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20  LITE_OPEN_WAL   
6490: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
64a0: 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  80000  /* VFS on
64b0: 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76  ly */../* Reserv
64c0: 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20  ed:             
64d0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
64e0: 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  F00000 */../*.**
64f0: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63   CAPI3REF: Devic
6500: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63  e Characteristic
6510: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76  s.**.** The xDev
6520: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
6530: 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  cs method of the
6540: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6550: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  hods].** object 
6560: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
6570: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65  er which is a ve
6580: 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a  ctor of these.**
6590: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
65a0: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
65b0: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
65c0: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
65d0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
65e0: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
65f0: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
6600: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
6610: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** T
6620: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6630: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
6640: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
6650: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
6660: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
6670: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6680: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
6690: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
66a0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
66b0: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
66c0: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
66d0: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
66e0: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
66f0: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
6700: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
6710: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
6720: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6730: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
6740: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
6750: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
6760: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
6770: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
6780: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
6790: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
67a0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
67b0: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
67c0: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
67d0: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
67e0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
67f0: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
6800: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
6810: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
6820: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
6830: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
6840: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
6850: 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54  te().  The SQLIT
6860: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
6870: 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70  E_OVERWRITE prop
6880: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
6890: 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20  ** after reboot 
68a0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73  following a cras
68b0: 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c  h or power loss,
68c0: 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20   the only bytes 
68d0: 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61  in a.** file tha
68e0: 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61  t were written a
68f0: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
6900: 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61  n level might ha
6910: 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e  ve changed.** an
6920: 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20  d that adjacent 
6930: 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65  bytes, even byte
6940: 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
6950: 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20  e sector are.** 
6960: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
6970: 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
6980: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6990: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
69a0: 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69  PEN.** flag indi
69b0: 63 61 74 65 73 20 74 68 61 74 20 61 20 66 69 6c  cates that a fil
69c0: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65  e cannot be dele
69d0: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20  ted when open.  
69e0: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  The.** SQLITE_IO
69f0: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c  CAP_IMMUTABLE fl
6a00: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
6a10: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e  t the file is on
6a20: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65  .** read-only me
6a30: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62  dia and cannot b
6a40: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62  e changed even b
6a50: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68  y processes with
6a60: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69  .** elevated pri
6a70: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66  vileges..*/.#def
6a80: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a90: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
6aa0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6ab0: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
6ac0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
6ad0: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
6ae0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
6af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6b00: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
6b10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
6b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6b30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
6b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6b50: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
6b60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6b70: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
6b80: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
6b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6ba0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
6bb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6bc0: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
6bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6be0: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
6bf0: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
6c00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6c10: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
6c20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6c30: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
6c40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6c50: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6c60: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6c70: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6c80: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
6c90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6ca0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6cb0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6cc0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
6cd0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
6ce0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6cf0: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6d00: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
6d10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6d20: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6d30: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
6d40: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
6d50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
6d60: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
6d70: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f     0x00002000../
6d80: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
6d90: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
6da0: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
6db0: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
6dc0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6dd0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
6de0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
6df0: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
6e00: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
6e10: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
6e20: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
6e30: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6e40: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
6e50: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
6e60: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
6e70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6e80: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
6e90: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
6ea0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
6eb0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
6ec0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6ed0: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
6ee0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
6ef0: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
6f00: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6f10: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
6f20: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
6f30: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
6f40: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
6f50: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
6f60: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6f70: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
6f80: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
6f90: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
6fa0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6fb0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
6fc0: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
6fd0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6fe0: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
6ff0: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
7000: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
7010: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
7020: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
7030: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
7040: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
7050: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
7060: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
7070: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
7080: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
7090: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
70a0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
70b0: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
70c0: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
70d0: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
70e0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
70f0: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
7100: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
7110: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
7120: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
7130: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
7140: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
7150: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
7160: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
7170: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7180: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7190: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
71a0: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
71b0: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
71c0: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
71d0: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
71e0: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
71f0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
7200: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
7210: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
7220: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
7230: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
7240: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
7250: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
7260: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
7270: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7280: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
7290: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
72a0: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
72b0: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
72c0: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
72d0: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
72e0: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
72f0: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
7300: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
7310: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
7320: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
7330: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
7340: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7350: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
7360: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
7370: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
7380: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
7390: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
73a0: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
73b0: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
73c0: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
73d0: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
73e0: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
73f0: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
7400: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
7410: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
7420: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7430: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
7440: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7450: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
7460: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
7470: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
7480: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
7490: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
74a0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
74b0: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
74c0: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
74d0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
74e0: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
74f0: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
7500: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
7510: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
7520: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
7530: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
7540: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
7550: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
7560: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
7570: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
7580: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
7590: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
75a0: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
75b0: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
75c0: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
75d0: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
75e0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
75f0: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
7600: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
7610: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
7620: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
7630: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
7640: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
7650: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
7660: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
7670: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
7680: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
7690: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
76a0: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
76b0: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
76c0: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
76d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
76e0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
76f0: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
7700: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
7710: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
7720: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
7730: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7740: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
7750: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7760: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
7770: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
7780: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
7790: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
77a0: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
77b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
77c0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
77d0: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
77e0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
77f0: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
7800: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
7810: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
7820: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
7830: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
7840: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
7850: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
7860: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
7870: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7880: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
7890: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
78a0: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
78b0: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
78c0: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
78d0: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
78e0: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
78f0: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
7900: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
7910: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7920: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
7930: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
7940: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
7950: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
7960: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
7970: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
7980: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7990: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
79a0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
79b0: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
79c0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
79d0: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
79e0: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
79f0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
7a00: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
7a10: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
7a20: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
7a30: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
7a40: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
7a50: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
7a60: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
7a70: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
7a80: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
7a90: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
7aa0: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
7ab0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7ac0: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
7ad0: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
7ae0: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
7af0: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
7b00: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
7b10: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
7b20: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
7b30: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
7b40: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
7b50: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
7b60: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
7b70: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
7b80: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
7b90: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7ba0: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
7bb0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7bc0: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
7bd0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7be0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
7bf0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7c00: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
7c10: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
7c20: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
7c30: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
7c40: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
7c50: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
7c60: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
7c70: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
7c80: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
7c90: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
7ca0: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
7cb0: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
7cc0: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
7cd0: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
7ce0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
7cf0: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
7d00: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
7d10: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
7d20: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
7d30: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
7d40: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
7d50: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
7d60: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
7d70: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
7d80: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
7d90: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
7da0: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
7db0: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
7dc0: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
7dd0: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
7de0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7df0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
7e00: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
7e10: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
7e20: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
7e30: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
7e40: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
7e50: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
7e60: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
7e70: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
7e80: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
7e90: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
7ea0: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
7eb0: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
7ec0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
7ed0: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
7ee0: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
7ef0: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
7f00: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
7f10: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
7f20: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
7f30: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
7f40: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
7f50: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
7f60: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
7f70: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
7f80: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
7f90: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
7fa0: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
7fb0: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
7fc0: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
7fd0: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
7fe0: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
7ff0: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
8000: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f  e..** A [file co
8010: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20  ntrol opcodes | 
8020: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
8030: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
8040: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
8050: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
8060: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
8070: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
8080: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
8090: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
80a0: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
80b0: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
80c0: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
80d0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
80e0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
80f0: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
8100: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
8110: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
8120: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
8130: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
8140: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
8150: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
8160: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
8170: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
8180: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
8190: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
81a0: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
81b0: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
81c0: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
81d0: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
81e0: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
81f0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
8200: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
8210: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
8220: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
8230: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
8240: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
8250: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
8260: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
8270: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8280: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8290: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
82a0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
82b0: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
82c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
82d0: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
82e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
82f0: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
8300: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8310: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
8320: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8330: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
8340: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8350: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
8360: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8370: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
8380: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8390: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
83a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
83b0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
83c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
83d0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
83e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
83f0: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
8400: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a  LE_WHEN_OPEN].**
8410: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8420: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
8430: 45 52 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e  ERWRITE].** <li>
8440: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49   [SQLITE_IOCAP_I
8450: 4d 4d 55 54 41 42 4c 45 5d 0a 2a 2a 20 3c 2f 75  MMUTABLE].** </u
8460: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
8470: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8480: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
8490: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
84a0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
84b0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
84c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
84d0: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
84e0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
84f0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
8500: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
8510: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
8520: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
8530: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
8540: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
8550: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
8560: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
8570: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
8580: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
8590: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
85a0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
85b0: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
85c0: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
85d0: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
85e0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
85f0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
8600: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
8610: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
8620: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8630: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
8640: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
8650: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
8660: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
8670: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
8680: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
8690: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
86a0: 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29  **.** If xRead()
86b0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
86c0: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
86d0: 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69   it must also fi
86e0: 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72  ll.** in the unr
86f0: 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20  ead portions of 
8700: 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20  the buffer with 
8710: 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68  zeros.  A VFS th
8720: 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a  at.** fails to z
8730: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
8740: 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20  eads might seem 
8750: 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65  to work.  Howeve
8760: 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f  r,.** failure to
8770: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
8780: 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e   reads will even
8790: 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a  tually lead to.*
87a0: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75  * database corru
87b0: 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ption..*/.typede
87c0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
87d0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  _io_methods sqli
87e0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a  te3_io_methods;.
87f0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
8800: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  o_methods {.  in
8810: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
8820: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
8830: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
8840: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74  t (*xRead)(sqlit
8850: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c  e3_file*, void*,
8860: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
8870: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8880: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29  .  int (*xWrite)
8890: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
88a0: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
88b0: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
88c0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
88d0: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28  nt (*xTruncate)(
88e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
88f0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a  qlite3_int64 siz
8900: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  e);.  int (*xSyn
8910: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  c)(sqlite3_file*
8920: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
8930: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29  int (*xFileSize)
8940: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8950: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
8960: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Size);.  int (*x
8970: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8980: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8990: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69   (*xUnlock)(sqli
89a0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
89b0: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52  .  int (*xCheckR
89c0: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c  eservedLock)(sql
89d0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
89e0: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
89f0: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
8a00: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8a10: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
8a20: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
8a30: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
8a40: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8a50: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
8a60: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
8a70: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d  3_file*);.  /* M
8a80: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8a90: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8aa0: 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 1 */.  int (*
8ab0: 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33  xShmMap)(sqlite3
8ac0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c  _file*, int iPg,
8ad0: 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20   int pgsz, int, 
8ae0: 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29  void volatile**)
8af0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f  ;.  int (*xShmLo
8b00: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8b10: 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69  *, int offset, i
8b20: 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29  nt n, int flags)
8b30: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42  ;.  void (*xShmB
8b40: 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f  arrier)(sqlite3_
8b50: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8b60: 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74  xShmUnmap)(sqlit
8b70: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65  e3_file*, int de
8b80: 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20  leteFlag);.  /* 
8b90: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8ba0: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8bb0: 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 2 */.  int (
8bc0: 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33  *xFetch)(sqlite3
8bd0: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8be0: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74  int64 iOfst, int
8bf0: 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70   iAmt, void **pp
8c00: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65  );.  int (*xUnfe
8c10: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
8c20: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8c30: 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70  4 iOfst, void *p
8c40: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
8c50: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8c60: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f  for version 3 */
8c70: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
8c80: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
8c90: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
8ca0: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
8cb0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
8cc0: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
8cd0: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a  ntrol Opcodes.**
8ce0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65   KEYWORDS: {file
8cf0: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
8d00: 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  } {file control 
8d10: 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68  opcode}.**.** Th
8d20: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
8d30: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
8d40: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
8d50: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
8d60: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
8d70: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
8d80: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
8d90: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8da0: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
8db0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c  rface..**.** <ul
8dc0: 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  >.** <li>[[SQLIT
8dd0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
8de0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
8df0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
8e00: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
8e10: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
8e20: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
8e30: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
8e40: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8e50: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75   to write the cu
8e60: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a  rrent state of.*
8e70: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20  * the lock (one 
8e80: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  of [SQLITE_LOCK_
8e90: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  NONE], [SQLITE_L
8ea0: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
8eb0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
8ec0: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERVED], [SQLITE_
8ed0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
8ee0: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  r [SQLITE_LOCK_E
8ef0: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e  XCLUSIVE]).** in
8f00: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  to an integer th
8f10: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75  at the pArg argu
8f20: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20  ment points to. 
8f30: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
8f40: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
8f50: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73  g testing and is
8f60: 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
8f70: 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f  when the SQLITE_
8f80: 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  TEST.** compile-
8f90: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75  time option is u
8fa0: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  sed..**.** <li>[
8fb0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
8fc0: 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65  ZE_HINT]].** The
8fd0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
8fe0: 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65  IZE_HINT] opcode
8ff0: 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69   is used by SQLi
9000: 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56  te to give the V
9010: 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69  FS.** layer a hi
9020: 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20  nt of how large 
9030: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
9040: 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62  e will grow to b
9050: 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  e during the.** 
9060: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
9070: 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ion.  This hint 
9080: 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  is not guarantee
9090: 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65  d to be accurate
90a0: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66   but it.** is of
90b0: 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20  ten close.  The 
90c0: 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d  underlying VFS m
90d0: 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70  ight choose to p
90e0: 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62  reallocate datab
90f0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63  ase.** file spac
9100: 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20  e based on this 
9110: 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  hint in order to
9120: 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20   help writes to 
9130: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
9140: 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e  file run faster.
9150: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9160: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
9170: 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SIZE]].** The [S
9180: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
9190: 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69  K_SIZE] opcode i
91a0: 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73  s used to reques
91b0: 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a  t that the VFS.*
91c0: 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72  * extends and tr
91d0: 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61  uncates the data
91e0: 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75  base file in chu
91f0: 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70  nks of a size sp
9200: 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
9210: 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72  e user. The four
9220: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  th argument to [
9230: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9240: 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a  trol()] should .
9250: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69  ** point to an i
9260: 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74  nteger (type int
9270: 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
9280: 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20   new chunk-size 
9290: 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68  to use.** for th
92a0: 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61  e nominated data
92b0: 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67  base. Allocating
92c0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73   database file s
92d0: 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a  pace in large.**
92e0: 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42   chunks (say 1MB
92f0: 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79   at a time), may
9300: 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73   reduce file-sys
9310: 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  tem fragmentatio
9320: 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65  n and.** improve
9330: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20   performance on 
9340: 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a  some systems..**
9350: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9360: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9370: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
9380: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
9390: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
93a0: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
93b0: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
93c0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
93d0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
93e0: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61  ciated with a pa
93f0: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
9400: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
9410: 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49    See also [SQLI
9420: 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c  TE_FCNTL_JOURNAL
9430: 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a  _POINTER]..**.**
9440: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9450: 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e  NTL_JOURNAL_POIN
9460: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
9470: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
9480: 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  AL_POINTER] opco
9490: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62  de is used to ob
94a0: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  tain a pointer.*
94b0: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
94c0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61  3_file] object a
94d0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
94e0: 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20  he journal file 
94f0: 28 65 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b  (either.** the [
9500: 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c  rollback journal
9510: 5d 20 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d  ] or the [write-
9520: 61 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20  ahead log]) for 
9530: 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
9540: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
9550: 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b  ion.  See also [
9560: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
9570: 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a  E_POINTER]..**.*
9580: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9590: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
95a0: 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72  D]].** No longer
95b0: 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c   in use..**.** <
95c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
95d0: 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20  L_SYNC]].** The 
95e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
95f0: 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  NC] opcode is ge
9600: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
9610: 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64  ly by SQLite and
9620: 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20  .** sent to the 
9630: 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  VFS immediately 
9640: 62 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63  before the xSync
9650: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
9660: 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62  ed on a.** datab
9670: 61 73 65 20 66 69 6c 65 20 64 65 73 63 72 69 70  ase file descrip
9680: 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  tor. Or, if the 
9690: 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20  xSync method is 
96a0: 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20  not invoked .** 
96b0: 62 65 63 61 75 73 65 20 74 68 65 20 75 73 65 72  because the user
96c0: 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20   has configured 
96d0: 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20  SQLite with .** 
96e0: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
96f0: 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e  ous | PRAGMA syn
9700: 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74  chronous=OFF] it
9710: 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70   is invoked in p
9720: 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20  lace .** of the 
9730: 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e  xSync method. In
9740: 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65   most cases, the
9750: 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
9760: 74 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a  t passed with.**
9770: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
9780: 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65  ol is NULL. Howe
9790: 76 65 72 2c 20 69 66 20 74 68 65 20 64 61 74 61  ver, if the data
97a0: 62 61 73 65 20 66 69 6c 65 20 69 73 20 62 65 69  base file is bei
97b0: 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20  ng synced.** as 
97c0: 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d  part of a multi-
97d0: 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c  database commit,
97e0: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f   the argument po
97f0: 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65  ints to a nul-te
9800: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
9810: 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
9820: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d  e transactions m
9830: 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69  aster-journal fi
9840: 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74  le name. VFSes t
9850: 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e  hat .** do not n
9860: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20  eed this signal 
9870: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
9880: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
9890: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
98a0: 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20   .** should not 
98b0: 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69  call [sqlite3_fi
98c0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
98d0: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
98e0: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a  s doing so may .
98f0: 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65 20 6f  ** disrupt the o
9900: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
9910: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
9920: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
9930: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
9940: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9950: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
9960: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9970: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
9980: 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20  HASETWO] opcode 
9990: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74  is generated int
99a0: 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74  ernally by SQLit
99b0: 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f  e.** and sent to
99c0: 20 74 68 65 20 56 46 53 20 61 66 74 65 72 20 61   the VFS after a
99d0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73   transaction has
99e0: 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20   been committed 
99f0: 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62  immediately.** b
9a00: 75 74 20 62 65 66 6f 72 65 20 74 68 65 20 64 61  ut before the da
9a10: 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b  tabase is unlock
9a20: 65 64 2e 20 56 46 53 65 73 20 74 68 61 74 20 64  ed. VFSes that d
9a30: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
9a40: 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64  signal.** should
9a50: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
9a60: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70   this opcode. Ap
9a70: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
9a80: 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73  d not call.** [s
9a90: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9aa0: 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73  rol()] with this
9ab0: 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67   opcode as doing
9ac0: 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20   so may disrupt 
9ad0: 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  the .** operatio
9ae0: 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c  n of the special
9af0: 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20  ized VFSes that 
9b00: 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20  do require it.  
9b10: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9b20: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
9b30: 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54  AV_RETRY]].** ^T
9b40: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9b50: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
9b60: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9b70: 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74  to configure aut
9b80: 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20  omatic.** retry 
9b90: 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72  counts and inter
9ba0: 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e  vals for certain
9bb0: 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74   disk I/O operat
9bc0: 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ions for the.** 
9bd0: 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e  windows [VFS] in
9be0: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
9bf0: 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20  e robustness in 
9c00: 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a  the presence of.
9c10: 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72  ** anti-virus pr
9c20: 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61  ograms.  By defa
9c30: 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73  ult, the windows
9c40: 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20   VFS will retry 
9c50: 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69  file read,.** fi
9c60: 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69  le write, and fi
9c70: 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74  le delete operat
9c80: 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69  ions up to 10 ti
9c90: 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61  mes, with a dela
9ca0: 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69  y.** of 25 milli
9cb0: 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74  seconds before t
9cc0: 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61  he first retry a
9cd0: 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61  nd with the dela
9ce0: 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20  y increasing.** 
9cf0: 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c  by an additional
9d00: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9d10: 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65   with each subse
9d20: 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68  quent retry.  Th
9d30: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c  is.** opcode all
9d40: 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61  ows these two va
9d50: 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73  lues (10 retries
9d60: 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63   and 25 millisec
9d70: 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a  onds of delay).*
9d80: 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64  * to be adjusted
9d90: 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72  .  The values ar
9da0: 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c  e changed for al
9db0: 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  l database conne
9dc0: 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e  ctions.** within
9dd0: 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73   the same proces
9de0: 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  s.  The argument
9df0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
9e00: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f   an array of two
9e10: 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65  .** integers whe
9e20: 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74  re the first int
9e30: 65 67 65 72 20 69 73 20 74 68 65 20 6e 65 77 20  eger is the new 
9e40: 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20  retry count and 
9e50: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e  the second.** in
9e60: 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c  teger is the del
9e70: 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69  ay.  If either i
9e80: 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69  nteger is negati
9e90: 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74  ve, then the set
9ea0: 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  ting.** is not c
9eb0: 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65  hanged but inste
9ec0: 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ad the prior val
9ed0: 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69  ue of that setti
9ee0: 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a  ng is written.**
9ef0: 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20   into the array 
9f00: 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20  entry, allowing 
9f10: 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72  the current retr
9f20: 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65  y settings to be
9f30: 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64  .** interrogated
9f40: 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70  .  The zDbName p
9f50: 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f  arameter is igno
9f60: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  red..**.** <li>[
9f70: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
9f80: 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e  RSIST_WAL]].** ^
9f90: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9fa0: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f  L_PERSIST_WAL] o
9fb0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9fc0: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
9fd0: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
9fe0: 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65  [WAL | Write Ahe
9ff0: 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e  ad Log] setting.
a000: 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68    By default, th
a010: 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77  e auxiliary.** w
a020: 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61  rite ahead log a
a030: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
a040: 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20   files used for 
a050: 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  transaction cont
a060: 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d  rol.** are autom
a070: 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
a080: 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74   when the latest
a090: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74   connection to t
a0a0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
a0b0: 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20  loses.  Setting 
a0c0: 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d  persistent WAL m
a0d0: 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65  ode causes those
a0e0: 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73   files to persis
a0f0: 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65  t after.** close
a100: 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68  .  Persisting th
a110: 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75  e files is usefu
a120: 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f  l when other pro
a130: 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e  cesses that do n
a140: 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65  ot.** have write
a150: 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74   permission on t
a160: 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e  he directory con
a170: 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61  taining the data
a180: 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a  base file want.*
a190: 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61  * to read the da
a1a0: 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20  tabase file, as 
a1b0: 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72  the WAL and shar
a1c0: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
a1d0: 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e  must exist.** in
a1e0: 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64   order for the d
a1f0: 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
a200: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75  adable.  The fou
a210: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a220: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a230: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a240: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a250: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a260: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a270: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a280: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a290: 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d  persistent WAL m
a2a0: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62  ode or 1 to enab
a2b0: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a  le persistent.**
a2c0: 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74   WAL mode.  If t
a2d0: 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31  he integer is -1
a2e0: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65  , then it is ove
a2f0: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
a300: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c  e current.** WAL
a310: 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74   persistence set
a320: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
a330: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
a340: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
a350: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
a360: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
a370: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
a380: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
a390: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74  o set or query t
a3a0: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74  he.** persistent
a3b0: 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72   "powersafe-over
a3c0: 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22  write" or "PSOW"
a3d0: 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50   setting.  The P
a3e0: 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64  SOW setting.** d
a3f0: 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53  etermines the [S
a400: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
a410: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
a420: 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78   bit of the.** x
a430: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
a440: 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54  stics methods. T
a450: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
a460: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
a470: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
a480: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
a490: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
a4a0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
a4b0: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
a4c0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
a4d0: 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67  sable zero-damag
a4e0: 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  e mode or 1 to e
a4f0: 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67  nable zero-damag
a500: 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74  e.** mode.  If t
a510: 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31  he integer is -1
a520: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65  , then it is ove
a530: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
a540: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72  e current.** zer
a550: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65  o-damage mode se
a560: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tting..**.** <li
a570: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a580: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e  OVERWRITE]].** ^
a590: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a5a0: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63  L_OVERWRITE] opc
a5b0: 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ode is invoked b
a5c0: 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f  y SQLite after o
a5d0: 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74  pening.** a writ
a5e0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f  e transaction to
a5f0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20   indicate that, 
a600: 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c  unless it is rol
a610: 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d  led back for som
a620: 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65  e.** reason, the
a630: 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65   entire database
a640: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76   file will be ov
a650: 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65  erwritten by the
a660: 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61   current .** tra
a670: 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69  nsaction. This i
a680: 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d  s used by VACUUM
a690: 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
a6a0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a6b0: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a  FCNTL_VFSNAME]].
a6c0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
a6d0: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f  FCNTL_VFSNAME] o
a6e0: 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65  pcode can be use
a6f0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  d to obtain the 
a700: 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20  names of.** all 
a710: 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56  [VFSes] in the V
a720: 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e  FS stack.  The n
a730: 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20  ames are of all 
a740: 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68  VFS shims and th
a750: 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f  e.** final botto
a760: 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20  m-level VFS are 
a770: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
a780: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
a790: 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
a7a0: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65  alloc()] and the
a7b0: 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65   result is store
a7c0: 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76  d in the char* v
a7d0: 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20  ariable.** that 
a7e0: 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
a7f0: 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33  eter of [sqlite3
a800: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
a810: 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54   points to..** T
a820: 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73  he caller is res
a830: 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65  ponsible for fre
a840: 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20  eing the memory 
a850: 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77  when done.  As w
a860: 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d  ith.** all file-
a870: 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c  control actions,
a880: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61   there is no gua
a890: 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73  rantee that this
a8a0: 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a   will actually.*
a8b0: 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20  * do anything.  
a8c0: 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69  Callers should i
a8d0: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68  nitialize the ch
a8e0: 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20  ar* variable to 
a8f0: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
a900: 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66  r in case this f
a910: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e  ile-control is n
a920: 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20  ot implemented. 
a930: 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   This file-contr
a940: 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65  ol.** is intende
a950: 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63  d for diagnostic
a960: 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a   use only..**.**
a970: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a980: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d  NTL_VFS_POINTER]
a990: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a9a0: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
a9b0: 54 45 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64  TER] opcode find
a9c0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
a9d0: 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20  he top-level.** 
a9e0: 5b 56 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c  [VFSes] currentl
a9f0: 79 20 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65  y in use.  ^(The
aa00: 20 61 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a   argument X in.*
aa10: 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63  * sqlite3_file_c
aa20: 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45  ontrol(db,SQLITE
aa30: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
aa40: 45 52 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a  ER,X) must be.**
aa50: 20 6f 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74   of type "[sqlit
aa60: 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68  e3_vfs] **".  Th
aa70: 69 73 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20  is opcodes will 
aa80: 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70  set *X.** to a p
aa90: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f  ointer to the to
aaa0: 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a  p-level VFS.)^.*
aab0: 2a 20 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72  * ^When there ar
aac0: 65 20 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73  e multiple VFS s
aad0: 68 69 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63  hims in the stac
aae0: 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66  k, this opcode f
aaf0: 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65  inds the.** uppe
ab00: 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79  r-most shim only
ab10: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
ab20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
ab30: 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72  A]].** ^Whenever
ab40: 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74   a [PRAGMA] stat
ab50: 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c  ement is parsed,
ab60: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54   an [SQLITE_FCNT
ab70: 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69  L_PRAGMA] .** fi
ab80: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65  le control is se
ab90: 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b  nt to the open [
aba0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
abb0: 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69  ject correspondi
abc0: 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74  ng.** to the dat
abd0: 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68  abase file to wh
abe0: 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73  ich the pragma s
abf0: 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e  tatement refers.
ac00: 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a   ^The argument.*
ac10: 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45  * to the [SQLITE
ac20: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
ac30: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61  ile control is a
ac40: 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f  n array of.** po
ac50: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
ac60: 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68  s (char**) in wh
ac70: 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ich the second e
ac80: 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72  lement of the ar
ac90: 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ray.** is the na
aca0: 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61  me of the pragma
acb0: 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65   and the third e
acc0: 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72  lement is the ar
acd0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
ace0: 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20   pragma or NULL 
acf0: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61  if the pragma ha
ad00: 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20  s no argument.  
ad10: 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72  ^The handler for
ad20: 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46   an.** [SQLITE_F
ad30: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
ad40: 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70  e control can op
ad50: 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68  tionally make th
ad60: 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a  e first element.
ad70: 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a  ** of the char**
ad80: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20   argument point 
ad90: 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61  to a string obta
ada0: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
adb0: 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a  e3_mprintf()].**
adc0: 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
add0: 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69  nt and that stri
ade0: 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74  ng will become t
adf0: 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65  he result of the
ae00: 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68   pragma or.** th
ae10: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
ae20: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61  if the pragma fa
ae30: 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20  ils. ^If the.** 
ae40: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ae50: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
ae60: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
ae70: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
ae80: 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50  en normal .** [P
ae90: 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e  RAGMA] processin
aea0: 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49  g continues.  ^I
aeb0: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
aec0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66  NTL_PRAGMA].** f
aed0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
aee0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
aef0: 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72   then the parser
af00: 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
af10: 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e  e.** VFS has han
af20: 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20  dled the PRAGMA 
af30: 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70  itself and the p
af40: 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20  arser generates 
af50: 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61  a no-op.** prepa
af60: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66  red statement if
af70: 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69   result string i
af80: 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20  s NULL, or that 
af90: 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a  returns a copy.*
afa0: 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
afb0: 73 74 72 69 6e 67 20 69 66 20 74 68 65 20 73 74  string if the st
afc0: 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c  ring is non-NULL
afd0: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  ..** ^If the [SQ
afe0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
aff0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
b000: 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72  returns.** any r
b010: 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72  esult code other
b020: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
b030: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  ] or [SQLITE_NOT
b040: 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61  FOUND], that mea
b050: 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56  ns.** that the V
b060: 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61  FS encountered a
b070: 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61  n error while ha
b080: 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47  ndling the [PRAG
b090: 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63  MA] and the.** c
b0a0: 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68  ompilation of th
b0b0: 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77  e PRAGMA fails w
b0c0: 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
b0d0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b0e0: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
b0f0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73  e control occurs
b100: 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   at the beginnin
b110: 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74  g of pragma stat
b120: 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61  ement analysis a
b130: 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61  nd so.** it is a
b140: 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20  ble to override 
b150: 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41  built-in [PRAGMA
b160: 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
b170: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b180: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
b190: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ER]].** ^The [SQ
b1a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
b1b0: 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d  ANDLER].** file-
b1c0: 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69  control may be i
b1d0: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
b1e0: 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
b1f0: 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20   file handle.** 
b200: 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74  shortly after it
b210: 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72   is opened in or
b220: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61  der to provide a
b230: 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68   custom VFS with
b240: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68   access.** to th
b250: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75  e connections bu
b260: 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy-handler callb
b270: 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e  ack. The argumen
b280: 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f  t is of type (vo
b290: 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61  id **).** - an a
b2a0: 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69  rray of two (voi
b2b0: 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65  d *) values. The
b2c0: 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20   first (void *) 
b2d0: 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a  actually points.
b2e0: 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  ** to a function
b2f0: 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a   of type (int (*
b300: 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f  )(void *)). In o
b310: 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74  rder to invoke t
b320: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  he connections.*
b330: 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20  * busy-handler, 
b340: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68  this function sh
b350: 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20  ould be invoked 
b360: 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20  with the second 
b370: 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74  (void *) in.** t
b380: 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20  he array as the 
b390: 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49  only argument. I
b3a0: 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e  f it returns non
b3b0: 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
b3c0: 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  operation.** sho
b3d0: 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20  uld be retried. 
b3e0: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65  If it returns ze
b3f0: 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56  ro, the custom V
b400: 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f  FS should abando
b410: 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
b420: 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a   operation..**.*
b430: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b440: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
b450: 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74  E]].** ^Applicat
b460: 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74  ion can invoke t
b470: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b480: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66  _TEMPFILENAME] f
b490: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74  ile-control.** t
b4a0: 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65  o have SQLite ge
b4b0: 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70  nerate a.** temp
b4c0: 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75  orary filename u
b4d0: 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c  sing the same al
b4e0: 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20  gorithm that is 
b4f0: 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65  followed to gene
b500: 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  rate.** temporar
b510: 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20  y filenames for 
b520: 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20  TEMP tables and 
b530: 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75  other internal u
b540: 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67  ses.  The.** arg
b550: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
b560: 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77  a char** which w
b570: 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69  ill be filled wi
b580: 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a  th the filename.
b590: 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ** written into 
b5a0: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
b5b0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
b5c0: 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61  lloc()].  The ca
b5d0: 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69  ller should.** i
b5e0: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
b5f0: 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65  ree()] on the re
b600: 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20  sult to avoid a 
b610: 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a  memory leak..**.
b620: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b630: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
b640: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b650: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
b660: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
b670: 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20  s used to query 
b680: 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61  or set the.** ma
b690: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
b6a0: 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20  bytes that will 
b6b0: 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f  be used for memo
b6c0: 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a  ry-mapped I/O..*
b6d0: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
b6e0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
b6f0: 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73   value of type s
b700: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61  qlite3_int64 tha
b710: 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73  t.** is an advis
b720: 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ory maximum numb
b730: 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
b740: 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72  he file to memor
b750: 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70  y map.  The.** p
b760: 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72  ointer is overwr
b770: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f  itten with the o
b780: 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c  ld value.  The l
b790: 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e  imit is not chan
b7a0: 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61  ged if.** the va
b7b0: 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70  lue originally p
b7c0: 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67  ointed to is neg
b7d0: 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68  ative, and so th
b7e0: 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20  e current limit 
b7f0: 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69  .** can be queri
b800: 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e  ed by passing in
b810: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
b820: 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e  negative number.
b830: 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63    This.** file-c
b840: 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69  ontrol is used i
b850: 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70  nternally to imp
b860: 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d  lement [PRAGMA m
b870: 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a  map_size]..**.**
b880: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b890: 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54  NTL_TRACE]].** T
b8a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b8b0: 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e  _TRACE] file con
b8c0: 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64  trol provides ad
b8d0: 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69  visory informati
b8e0: 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53  on.** to the VFS
b8f0: 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20   about what the 
b900: 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66  higher layers of
b910: 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63   the SQLite stac
b920: 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20  k are doing..** 
b930: 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  This file contro
b940: 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d  l is used by som
b950: 65 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74  e VFS activity t
b960: 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a  racing [shims]..
b970: 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
b980: 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  is a zero-termin
b990: 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69  ated string.  Hi
b9a0: 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74  gher layers in t
b9b0: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61  he.** SQLite sta
b9c0: 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20  ck may generate 
b9d0: 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69  instances of thi
b9e0: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
b9f0: 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  f.** the [SQLITE
ba00: 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  _USE_FCNTL_TRACE
ba10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
ba20: 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
ba30: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
ba40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
ba50: 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  OVED]].** The [S
ba60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
ba70: 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74  MOVED] file cont
ba80: 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69  rol interprets i
ba90: 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61  ts argument as a
baa0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
bab0: 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74  n integer and it
bac0: 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61   writes a boolea
bad0: 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65  n into that inte
bae0: 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a  ger depending.**
baf0: 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e   on whether or n
bb00: 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20  ot the file has 
bb10: 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f  been renamed, mo
bb20: 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20  ved, or deleted 
bb30: 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20  since it.** was 
bb40: 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a  first opened..**
bb50: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
bb60: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54  _FCNTL_WIN32_GET
bb70: 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65  _HANDLE]].** The
bb80: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
bb90: 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d  IN32_GET_HANDLE]
bba0: 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75   opcode can be u
bbb0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
bbc0: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
bbd0: 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64  native file hand
bbe0: 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  le associated wi
bbf0: 74 68 20 61 20 66 69 6c 65 20 68 61 6e 64 6c 65  th a file handle
bc00: 2e 20 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20  .  This file.** 
bc10: 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65  control interpre
bc20: 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20  ts its argument 
bc30: 61 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  as a pointer to 
bc40: 61 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61  a native file ha
bc50: 6e 64 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74  ndle and.** writ
bc60: 65 73 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  es the resulting
bc70: 20 76 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a   value there..**
bc80: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
bc90: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54  _FCNTL_WIN32_SET
bca0: 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65  _HANDLE]].** The
bcb0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
bcc0: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d  IN32_SET_HANDLE]
bcd0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
bce0: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
bcf0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
bd00: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
bd10: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
bd20: 20 73 77 61 70 20 74 68 65 20 66 69 6c 65 20 68   swap the file h
bd30: 61 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f  andle with the o
bd40: 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  ne.** pointed to
bd50: 20 62 79 20 74 68 65 20 70 41 72 67 20 61 72 67   by the pArg arg
bd60: 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70  ument.  This cap
bd70: 61 62 69 6c 69 74 79 20 69 73 20 75 73 65 64 20  ability is used 
bd80: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a  during testing.*
bd90: 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  * and only needs
bda0: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
bdb0: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
bdc0: 54 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  T is defined..**
bdd0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
bde0: 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b  _FCNTL_WAL_BLOCK
bdf0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
be00: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
be10: 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74  K] is a signal t
be20: 6f 20 74 68 65 20 56 46 53 20 6c 61 79 65 72 20  o the VFS layer 
be30: 74 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a  that it might.**
be40: 20 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73   be advantageous
be50: 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65   to block on the
be60: 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69   next WAL lock i
be70: 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f  f the lock is no
be80: 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a  t immediately.**
be90: 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65   available.  The
bea0: 20 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69   WAL subsystem i
beb0: 73 73 75 65 73 20 74 68 69 73 20 73 69 67 6e 61  ssues this signa
bec0: 6c 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a  l during rare.**
bed0: 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69   circumstances i
bee0: 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61  n order to fix a
bef0: 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72   problem with pr
bf00: 69 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e  iority inversion
bf10: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
bf20: 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74  s should <em>not
bf30: 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66  </em> use this f
bf40: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a  ile-control..**.
bf50: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
bf60: 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a  FCNTL_ZIPVFS]].*
bf70: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
bf80: 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f  NTL_ZIPVFS] opco
bf90: 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  de is implemente
bfa0: 64 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79  d by zipvfs only
bfb0: 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56  . All other.** V
bfc0: 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  FS should return
bfd0: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
bfe0: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
bff0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
c000: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d  LITE_FCNTL_RBU]]
c010: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
c020: 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64  FCNTL_RBU] opcod
c030: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
c040: 20 62 79 20 74 68 65 20 73 70 65 63 69 61 6c 20   by the special 
c050: 56 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74  VFS used by.** t
c060: 68 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e  he RBU extension
c070: 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65   only.  All othe
c080: 72 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74  r VFS should ret
c090: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  urn SQLITE_NOTFO
c0a0: 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20  UND for.** this 
c0b0: 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75  opcode.  .** </u
c0c0: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
c0d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
c0e0: 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  TATE            
c0f0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
c100: 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f  ITE_FCNTL_GET_LO
c110: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
c120: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
c130: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43  TE_FCNTL_SET_LOC
c140: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
c150: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
c160: 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52  E_FCNTL_LAST_ERR
c170: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NO              
c180: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
c190: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
c1a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
c1b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c1c0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
c1d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
c1e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c1f0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
c200: 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23  R            7.#
c210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c220: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
c230: 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64              8.#d
c240: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c250: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
c260: 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65  Y          9.#de
c270: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c280: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20  L_PERSIST_WAL   
c290: 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
c2a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c2b0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20  _OVERWRITE      
c2c0: 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69          11.#defi
c2d0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c2e0: 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20  VFSNAME         
c2f0: 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e         12.#defin
c300: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
c310: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
c320: 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65  TE    13.#define
c330: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52   SQLITE_FCNTL_PR
c340: 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
c350: 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20       14.#define 
c360: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
c370: 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20  YHANDLER        
c380: 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53      15.#define S
c390: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
c3a0: 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20  FILENAME        
c3b0: 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
c3c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
c3d0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
c3e0: 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c    18.#define SQL
c3f0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20  ITE_FCNTL_TRACE 
c400: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c410: 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   19.#define SQLI
c420: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
c430: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
c440: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
c450: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20  E_FCNTL_SYNC    
c460: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
c470: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
c480: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
c490: 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32  ASETWO        22
c4a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c4b0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
c4c0: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a  HANDLE       23.
c4d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c4e0: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20  CNTL_WAL_BLOCK  
c4f0: 20 20 20 20 20 20 20 20 20 20 20 20 32 34 0a 23              24.#
c500: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c510: 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 20 20 20  NTL_ZIPVFS      
c520: 20 20 20 20 20 20 20 20 20 20 20 32 35 0a 23 64             25.#d
c530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c540: 54 4c 5f 52 42 55 20 20 20 20 20 20 20 20 20 20  TL_RBU          
c550: 20 20 20 20 20 20 20 20 20 20 32 36 0a 23 64 65            26.#de
c560: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c570: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20 20 20  L_VFS_POINTER   
c580: 20 20 20 20 20 20 20 20 20 32 37 0a 23 64 65 66           27.#def
c590: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c5a0: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
c5b0: 20 20 20 20 20 20 20 20 32 38 0a 23 64 65 66 69          28.#defi
c5c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c5d0: 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45  WIN32_GET_HANDLE
c5e0: 20 20 20 20 20 20 20 32 39 0a 23 64 65 66 69 6e         29.#defin
c5f0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
c600: 44 42 20 20 20 20 20 20 20 20 20 20 20 20 20 20  DB              
c610: 20 20 20 20 20 20 33 30 0a 0a 2f 2a 20 64 65 70        30../* dep
c620: 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f  recated names */
c630: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c640: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
c650: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43  E      SQLITE_FC
c660: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
c670: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51  YFILE.#define SQ
c680: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_SET_LOCKPRO
c690: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49  XYFILE      SQLI
c6a0: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43  TE_FCNTL_SET_LOC
c6b0: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69  KPROXYFILE.#defi
c6c0: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
c6d0: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
c6e0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
c6f0: 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a  ST_ERRNO.../*.**
c700: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
c710: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68   Handle.**.** Th
c720: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
c730: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
c740: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
c750: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
c760: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
c770: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
c780: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
c790: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
c7a0: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
c7b0: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
c7c0: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
c7d0: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
c7e0: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
c7f0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
c800: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
c810: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
c820: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
c830: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
c840: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
c850: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
c860: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
c870: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
c880: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
c890: 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73   Loadable Extens
c8a0: 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20  ion Thunk.**.** 
c8b0: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
c8c0: 20 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f   opaque sqlite3_
c8d0: 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72  api_routines str
c8e0: 75 63 74 75 72 65 20 69 73 20 70 61 73 73 65 64  ucture is passed
c8f0: 20 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64   as.** the third
c900: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e   parameter to en
c910: 74 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c  try points of [l
c920: 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f  oadable extensio
c930: 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74  ns].  This.** st
c940: 72 75 63 74 75 72 65 20 6d 75 73 74 20 62 65 20  ructure must be 
c950: 74 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64  typedefed in ord
c960: 65 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  er to work aroun
c970: 64 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69  d compiler warni
c980: 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70  ngs.** on some p
c990: 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70  latforms..*/.typ
c9a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
c9b0: 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73  te3_api_routines
c9c0: 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75   sqlite3_api_rou
c9d0: 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tines;../*.** CA
c9e0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
c9f0: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
ca00: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
ca10: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
ca20: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
ca30: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
ca40: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
ca50: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
ca60: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
ca70: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
ca80: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
ca90: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
caa0: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
cab0: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
cac0: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20  ystem".  See.** 
cad0: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64  the [VFS | VFS d
cae0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
caf0: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d  r further inform
cb00: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
cb10: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
cb20: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
cb30: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
cb40: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
cb50: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
cb60: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
cb70: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
cb80: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
cb90: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
cba0: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
cbb0: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
cbc0: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20  ncreased.  Note 
cbd0: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
cbe0: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
cbf0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
cc00: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
cc10: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65  ransaction betwe
cc20: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  en.** SQLite ver
cc30: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33  sion 3.5.9 and 3
cc40: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65  .6.0 and yet the
cc50: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
cc60: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66  was not.** modif
cc70: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
cc80: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
cc90: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
cca0: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
ccb0: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
ccc0: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
ccd0: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
cce0: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
ccf0: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
cd00: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
cd10: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
cd20: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
cd30: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
cd40: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
cd50: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
cd60: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
cd70: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
cd80: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
cd90: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
cda0: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
cdb0: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
cdc0: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
cdd0: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
cde0: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
cdf0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
ce00: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
ce10: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
ce20: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
ce30: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
ce40: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
ce50: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
ce60: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
ce70: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
ce80: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
ce90: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
cea0: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
ceb0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
cec0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
ced0: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
cee0: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
cef0: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
cf00: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
cf10: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
cf20: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
cf30: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
cf40: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
cf50: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
cf60: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
cf70: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
cf80: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
cf90: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
cfa0: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
cfb0: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
cfc0: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
cfd0: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
cfe0: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
cff0: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
d000: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
d010: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
d020: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  es..**.** [[sqli
d030: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a  te3_vfs.xOpen]].
d040: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
d050: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a  ntees that the z
d060: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
d070: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
d080: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
d090: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
d0a0: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
d0b0: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
d0c0: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f  () with an optio
d0d0: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64  nal suffix added
d0e0: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69  ..** ^If a suffi
d0f0: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  x is added to th
d100: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
d110: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a  meter, it will.*
d120: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73  * consist of a s
d130: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63  ingle "-" charac
d140: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  ter followed by 
d150: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20  no more than.** 
d160: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  11 alphanumeric 
d170: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61  and/or "-" chara
d180: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  cters..** ^SQLit
d190: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
d1a0: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
d1b0: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
d1c0: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
d1d0: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
d1e0: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
d1f0: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
d200: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
d210: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
d220: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
d230: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
d240: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
d250: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
d260: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
d270: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
d280: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
d290: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
d2a0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
d2b0: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
d2c0: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
d2d0: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
d2e0: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
d2f0: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
d300: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20  ile.  ^Whenever 
d310: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
d320: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
d330: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
d340: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
d350: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
d360: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
d370: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
d380: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
d390: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  ]..**.** The fla
d3a0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
d3b0: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
d3c0: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
d3d0: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
d3e0: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
d3f0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
d400: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
d410: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
d420: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
d430: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
d440: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
d450: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
d460: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
d470: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
d480: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78  REATE]. .** If x
d490: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
d4a0: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
d4b0: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
d4c0: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
d4d0: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
d4e0: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
d4f0: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
d500: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
d510: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65  ..**.** ^(SQLite
d520: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
d530: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
d540: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
d550: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
d560: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
d570: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
d580: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
d590: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
d5a0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
d5b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
d5c0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
d5d0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
d5e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
d5f0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
d600: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
d610: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
d620: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
d630: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
d640: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d650: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
d660: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
d670: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
d680: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
d690: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a  QLITE_OPEN_WAL].
d6a0: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
d6b0: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
d6c0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
d6d0: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
d6e0: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
d6f0: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
d700: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
d710: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
d720: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
d730: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
d740: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
d750: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
d760: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
d770: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
d780: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
d790: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
d7a0: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
d7b0: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
d7c0: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
d7d0: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
d7e0: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
d7f0: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
d800: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
d810: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
d820: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
d830: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
d840: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
d850: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
d860: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
d870: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
d880: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
d890: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
d8a0: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
d8b0: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
d8c0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
d8d0: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
d8e0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
d8f0: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
d900: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
d910: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
d920: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
d930: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
d940: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
d950: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
d960: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
d970: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
d980: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
d990: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
d9a0: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
d9b0: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
d9c0: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  sed.  ^The [SQLI
d9d0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d9e0: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
d9f0: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64  e set for TEMP d
da00: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65  atabases and the
da10: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61  ir journals, tra
da20: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61  nsient.** databa
da30: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72  ses, and subjour
da40: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nals..**.** ^The
da50: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
da60: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73  CLUSIVE] flag is
da70: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20   always used in 
da80: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  conjunction.** w
da90: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
daa0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61  OPEN_CREATE] fla
dab0: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74  g, which are bot
dac0: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e  h directly.** an
dad0: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f  alogous to the O
dae0: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41  _EXCL and O_CREA
daf0: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50  T flags of the P
db00: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41  OSIX open().** A
db10: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  PI.  The SQLITE_
db20: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66  OPEN_EXCLUSIVE f
db30: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64  lag, when paired
db40: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
db50: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
db60: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64  , is used to ind
db70: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20  icate that file 
db80: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a  should always.**
db90: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64   be created, and
dba0: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65   that it is an e
dbb0: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61  rror if it alrea
dbc0: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74  dy exists..** It
dbd0: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75   is <i>not</i> u
dbe0: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
dbf0: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
dc00: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f  be opened .** fo
dc10: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
dc20: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65  ss..**.** ^At le
dc30: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
dc40: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
dc50: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
dc60: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
dc70: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
dc80: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
dc90: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
dca0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
dcb0: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
dcc0: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
dcd0: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
dce0: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
dcf0: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
dd00: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
dd10: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
dd20: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
dd30: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
dd40: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
dd50: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
dd60: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
dd70: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
dd80: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
dd90: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
dda0: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
ddb0: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
ddc0: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
ddd0: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
dde0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
ddf0: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
de00: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
de10: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
de20: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
de30: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
de40: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
de50: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  call..**.** [[sq
de60: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73  lite3_vfs.xAcces
de70: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67  s]].** ^The flag
de80: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
de90: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b  ccess() may be [
dea0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
deb0: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  ISTS].** to test
dec0: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e   for the existen
ded0: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72  ce of a file, or
dee0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
def0: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a  READWRITE] to.**
df00: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
df10: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
df20: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f   and writable, o
df30: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
df40: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73  _READ].** to tes
df50: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
df60: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61   is at least rea
df70: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c  dable.   The fil
df80: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  e can be a.** di
df90: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  rectory..**.** ^
dfa0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
dfb0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
dfc0: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
dfd0: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
dfe0: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
dff0: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
e000: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
e010: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
e020: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
e030: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
e040: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
e050: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
e060: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
e070: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
e080: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
e090: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
e0a0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
e0b0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
e0c0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
e0d0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
e0e0: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
e0f0: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
e100: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
e110: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
e120: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
e130: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
e140: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
e150: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
e160: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78  s(), xSleep(), x
e170: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61  CurrentTime(), a
e180: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  nd xCurrentTimeI
e190: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66  nt64().** interf
e1a0: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72  aces are not str
e1b0: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
e1c0: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
e1d0: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
e1e0: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
e1f0: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
e200: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
e210: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
e220: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
e230: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
e240: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
e250: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
e260: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
e270: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
e280: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
e290: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
e2a0: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
e2b0: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
e2c0: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
e2d0: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
e2e0: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
e2f0: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
e300: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
e310: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
e320: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e  econds given.  ^
e330: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
e340: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
e350: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
e360: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
e370: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
e380: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66  d time as.** a f
e390: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
e3a0: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75  lue..** ^The xCu
e3b0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
e3c0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c   method returns,
e3d0: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   as an integer, 
e3e0: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61  the Julian.** Da
e3f0: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c  y Number multipl
e400: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  ied by 86400000 
e410: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
e420: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
e430: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
e440: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
e450: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
e460: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
e470: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
e480: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
e490: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
e4a0: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
e4b0: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
e4c0: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
e4d0: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
e4e0: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
e4f0: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
e500: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
e510: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
e520: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
e530: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
e540: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
e550: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73  .** ^The xSetSys
e560: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53  temCall(), xGetS
e570: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64  ystemCall(), and
e580: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c   xNestSystemCall
e590: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
e5a0: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79   are not used by
e5b0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
e5c0: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61  .  These optiona
e5d0: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
e5e0: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20   provided.** by 
e5f0: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61  some VFSes to fa
e600: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67  cilitate testing
e610: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65   of the VFS code
e620: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20  . By overriding 
e630: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73  .** system calls
e640: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20   with functions 
e650: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f  under its contro
e660: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61  l, a test progra
e670: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74  m can.** simulat
e680: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72  e faults and err
e690: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68  or conditions th
e6a0: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69  at would otherwi
e6b0: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a  se be difficult.
e6c0: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65  ** or impossible
e6d0: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65   to induce.  The
e6e0: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63   set of system c
e6f0: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65  alls that can be
e700: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76   overridden.** v
e710: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56  aries from one V
e720: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61  FS to another, a
e730: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73  nd from one vers
e740: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ion of the same 
e750: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  VFS to the.** ne
e760: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
e770: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65  s that use these
e780: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74   interfaces must
e790: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72   be prepared for
e7a0: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f   any.** or all o
e7b0: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  f these interfac
e7c0: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72  es to be NULL or
e7d0: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76   for their behav
e7e0: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ior to change.**
e7f0: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73   from one releas
e800: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20  e to the next.  
e810: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73  Applications mus
e820: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f  t not attempt to
e830: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f   access.** any o
e840: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20  f these methods 
e850: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  if the iVersion 
e860: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65  of the VFS is le
e870: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79  ss than 3..*/.ty
e880: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
e890: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
e8a0: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f  _vfs;.typedef vo
e8b0: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73  id (*sqlite3_sys
e8c0: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b  call_ptr)(void);
e8d0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
e8e0: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
e8f0: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
e900: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
e910: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75  rsion number (cu
e920: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20  rrently 3) */.  
e930: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
e940: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
e950: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
e960: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
e970: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
e980: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
e990: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
e9a0: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
e9b0: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
e9c0: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
e9d0: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
e9e0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
e9f0: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
ea00: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
ea10: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
ea20: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
ea30: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
ea40: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
ea50: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
ea60: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
ea70: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
ea80: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
ea90: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
eaa0: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
eab0: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
eac0: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
ead0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
eae0: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
eaf0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
eb00: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
eb10: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
eb20: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
eb30: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
eb40: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
eb50: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
eb60: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
eb70: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
eb80: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
eb90: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
eba0: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
ebb0: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
ebc0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ebd0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
ebe0: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
ebf0: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
ec00: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
ec10: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
ec20: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78  g);.  void (*(*x
ec30: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
ec40: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
ec50: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29   char *zSymbol))
ec60: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28  (void);.  void (
ec70: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
ec80: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
ec90: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
eca0: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
ecb0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
ecc0: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
ecd0: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
ece0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
ecf0: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
ed00: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
ed10: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
ed20: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
ed30: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
ed40: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ed50: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
ed60: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
ed70: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
ed80: 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
ed90: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
eda0: 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74  ect.  ** definit
edb0: 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74  ion.  Those that
edc0: 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65   follow are adde
edd0: 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f  d in version 2 o
ede0: 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69  r later.  */.  i
edf0: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
ee00: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
ee10: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
ee20: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
ee30: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
ee40: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
ee50: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
ee60: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
ee70: 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20  ect..  ** Those 
ee80: 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65  below are for ve
ee90: 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61  rsion 3 and grea
eea0: 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ter..  */.  int 
eeb0: 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xSetSystemCall
eec0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
eed0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
eee0: 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  e, sqlite3_sysca
eef0: 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74  ll_ptr);.  sqlit
ef00: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28  e3_syscall_ptr (
ef10: 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xGetSystemCall)
ef20: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
ef30: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
ef40: 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  );.  const char 
ef50: 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61  *(*xNextSystemCa
ef60: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
ef70: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
ef80: 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  ame);.  /*.  ** 
ef90: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
efa0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
efb0: 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66  s 1 through 3 of
efc0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
efd0: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77  object..  ** New
efe0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
eff0: 70 70 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72  ppended in futur
f000: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
f010: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
f020: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
f030: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
f040: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f  s happens. .  */
f050: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
f060: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
f070: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
f080: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
f090: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
f0a0: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
f0b0: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
f0c0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
f0d0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
f0e0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
f0f0: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
f100: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
f110: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
f120: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
f130: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
f140: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
f150: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
f160: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
f170: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
f180: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
f190: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
f1a0: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
f1b0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f1c0: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
f1d0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
f1e0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
f1f0: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20  named directory 
f200: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
f210: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a   and writable.**
f220: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   (in other words
f230: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62  , if files can b
f240: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64  e added, removed
f250: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69  , and renamed wi
f260: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65  thin.** the dire
f270: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53  ctory)..** The S
f280: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
f290: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20  DWRITE constant 
f2a0: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65  is currently use
f2b0: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a  d only by the.**
f2c0: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
f2d0: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
f2e0: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c  though this coul
f2f0: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  d change in a fu
f300: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
f310: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69  of SQLite..** Wi
f320: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
f330: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
f340: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
f350: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
f360: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
f370: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
f380: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61  CESS_READ consta
f390: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74  nt is.** current
f3a0: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67  ly unused, thoug
f3b0: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73  h it might be us
f3c0: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  ed in a future r
f3d0: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
f3e0: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
f3f0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
f400: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
f410: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
f420: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a  READWRITE 1   /*
f430: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20   Used by PRAGMA 
f440: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
f450: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tory */.#define 
f460: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
f470: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55  AD      2   /* U
f480: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nused */../*.** 
f490: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
f4a0: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
f4b0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
f4c0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
f4d0: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
f4e0: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
f4f0: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a  king operations.
f500: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68  ** allowed by th
f510: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
f520: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d of [sqlite3_io
f530: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a  _methods].  The.
f540: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  ** following are
f550: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20   the only legal 
f560: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
f570: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20  flags to the.** 
f580: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a  xShmLock method:
f590: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
f5a0: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
f5b0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
f5c0: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
f5d0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
f5e0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
f5f0: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  XCLUSIVE.** <li>
f600: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
f610: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
f620: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
f630: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
f640: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
f650: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75  EXCLUSIVE.** </u
f660: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e  l>.**.** When un
f670: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d  locking, the sam
f680: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c  e SHARED or EXCL
f690: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20  USIVE flag must 
f6a0: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a  be supplied as.*
f6b0: 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74  * was given on t
f6c0: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
f6d0: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54   lock.  .**.** T
f6e0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
f6f0: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f  od can transitio
f700: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  n between unlock
f710: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72  ed and SHARED or
f720: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  .** between unlo
f730: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49  cked and EXCLUSI
f740: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74  VE.  It cannot t
f750: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
f760: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20  n SHARED.** and 
f770: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64  EXCLUSIVE..*/.#d
f780: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
f790: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a  _UNLOCK       1.
f7a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
f7b0: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  HM_LOCK         
f7c0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
f7d0: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20  _SHM_SHARED     
f7e0: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
f7f0: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
f800: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
f810: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78  I3REF: Maximum x
f820: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a  ShmLock index.**
f830: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
f840: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69   method on [sqli
f850: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
f860: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a  may use values.*
f870: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
f880: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64  this upper bound
f890: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22   as its "offset"
f8a0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
f8b0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
f8c0: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74  ll never attempt
f8d0: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72   to acquire or r
f8e0: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b  elease a.** lock
f8f0: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73   outside of this
f900: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e   range.*/.#defin
f910: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f  e SQLITE_SHM_NLO
f920: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a  CK        8.../*
f930: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
f940: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
f950: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
f960: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
f970: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
f980: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
f990: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
f9a0: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
f9b0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f9c0: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
f9d0: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
f9e0: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
f9f0: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
fa00: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fa10: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
fa20: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
fa30: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
fa40: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
fa50: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
fa60: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
fa70: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
fa80: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
fa90: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
faa0: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
fab0: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
fac0: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
fad0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
fae0: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
faf0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
fb00: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
fb10: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
fb20: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
fb30: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fb40: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
fb50: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
fb60: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
fb70: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
fb80: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
fb90: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
fba0: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
fbb0: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
fbc0: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
fbd0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
fbe0: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
fbf0: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
fc00: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fc10: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
fc20: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
fc30: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
fc40: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
fc50: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
fc60: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
fc70: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
fc80: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
fc90: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
fca0: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
fcb0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fcc0: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
fcd0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fce0: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
fcf0: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
fd00: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
fd10: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
fd20: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
fd30: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
fd40: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
fd50: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
fd60: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
fd70: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
fd80: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
fd90: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
fda0: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
fdb0: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
fdc0: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
fdd0: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
fde0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
fdf0: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
fe00: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
fe10: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
fe20: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
fe30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
fe40: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
fe50: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
fe60: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
fe70: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
fe80: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
fe90: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
fea0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
feb0: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
fec0: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
fed0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fee0: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
fef0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
ff00: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
ff10: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
ff20: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
ff30: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
ff40: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
ff50: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ff60: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
ff70: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
ff80: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
ff90: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
ffa0: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
ffb0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
ffc0: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
ffd0: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
ffe0: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
fff0: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
10000 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
10010 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
10020 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
10030 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
10040 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
10050 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
10060 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
10070 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
10080 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
10090 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
100a0 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
100b0 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
100c0 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
100d0 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
100e0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
100f0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
10100 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
10110 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
10120 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
10130 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
10140 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10150 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
10160 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
10170 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
10180 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
10190 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
101a0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
101b0 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
101c0 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
101d0 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
101e0 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
101f0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
10200 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
10210 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
10220 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
10230 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
10240 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
10250 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10260 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
10270 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
10280 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
10290 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
102a0 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
102b0 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
102c0 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
102d0 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
102e0 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
102f0 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
10300 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
10310 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
10320 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
10330 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
10340 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
10350 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
10360 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
10370 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
10380 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
10390 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
103a0 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
103b0 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
103c0 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
103d0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
103e0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
103f0 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
10400 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
10410 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
10420 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
10430 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
10440 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
10450 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
10460 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
10470 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
10480 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
10490 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
104a0 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
104b0 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
104c0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
104d0 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
104e0 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
104f0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
10500 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
10510 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
10520 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
10530 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
10540 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
10550 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
10560 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
10570 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
10580 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
10590 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
105a0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
105b0 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
105c0 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
105d0 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
105e0 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
105f0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
10600 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
10610 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
10620 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
10630 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10640 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
10650 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
10660 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
10670 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
10680 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
10690 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
106a0 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
106b0 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
106c0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
106d0 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
106e0 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
106f0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
10700 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
10710 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
10720 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
10730 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10740 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
10750 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
10760 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
10770 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
10780 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
10790 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
107a0 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
107b0 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
107c0 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
107d0 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
107e0 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
107f0 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
10800 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
10810 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
10820 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
10830 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
10840 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
10850 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
10860 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
10870 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
10880 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
10890 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
108a0 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
108b0 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
108c0 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
108d0 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
108e0 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
108f0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
10900 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
10910 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
10920 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
10930 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
10940 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
10950 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
10960 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
10970 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68  ;.int sqlite3_sh
10980 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e  utdown(void);.in
10990 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
109a0 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  t(void);.int sql
109b0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
109c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
109d0 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
109e0 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
109f0 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
10a00 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
10a10 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
10a20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
10a30 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
10a40 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
10a50 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
10a60 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
10a70 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
10a80 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
10a90 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
10aa0 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
10ab0 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
10ac0 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
10ad0 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
10ae0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
10af0 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
10b00 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
10b10 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
10b20 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
10b30 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
10b40 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
10b50 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33  * <b>The sqlite3
10b60 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
10b70 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
10b80 64 73 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69  dsafe. The appli
10b90 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65  cation.** must e
10ba0 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74  nsure that no ot
10bb0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
10bc0 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65  faces are invoke
10bd0 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68  d by other.** th
10be0 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69  reads while sqli
10bf0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
10c00 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a  running.</b>.**.
10c10 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
10c20 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
10c30 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  e.** may only be
10c40 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74   invoked prior t
10c50 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61  o library initia
10c60 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  lization using.*
10c70 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  * [sqlite3_initi
10c80 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
10c90 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73  r shutdown by [s
10ca0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10cb0 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  )]..** ^If sqlit
10cc0 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63  e3_config() is c
10cd0 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
10ce0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10cf0 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a  )] and before.**
10d00 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
10d10 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69  wn()] then it wi
10d20 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
10d30 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65  _MISUSE..** Note
10d40 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
10d50 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  ^sqlite3_config(
10d60 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
10d70 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
10d80 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
10d90 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
10da0 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
10db0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
10dc0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
10dd0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
10de0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
10df0 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63  an integer.** [c
10e00 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10e10 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
10e20 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
10e30 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
10e40 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
10e50 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
10e60 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
10e70 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
10e80 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  the [configurati
10e90 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  on option].** in
10ea0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
10eb0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ent..**.** ^When
10ec0 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
10ed0 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
10ee0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10ef0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
10f00 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  _OK]..** ^If the
10f10 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f   option is unkno
10f20 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20  wn or SQLite is 
10f30 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68  unable to set th
10f40 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e  e option.** then
10f50 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
10f60 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  turns a non-zero
10f70 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
10f80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
10f90 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a  nfig(int, ...);.
10fa0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10fb0 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62   Configure datab
10fc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  ase connections.
10fd0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
10fe0 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
10ff0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
11000 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
11010 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
11020 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
11030 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
11040 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
11050 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
11060 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
11070 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11080 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
11090 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
110a0 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
110b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
110c0 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
110d0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
110e0 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** T
110f0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
11100 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
11110 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
11120 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
11130 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
11140 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
11150 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
11160 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
11170 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
11180 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
11190 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
111a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
111b0 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
111c0 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
111d0 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
111e0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
111f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
11200 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
11210 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
11220 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
11230 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
11240 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
11250 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
11260 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69  successful..*/.i
11270 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
11280 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
11290 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
112a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
112b0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
112c0 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
112d0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
112e0 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
112f0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
11300 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
11310 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
11320 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11330 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
11340 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
11350 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
11360 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
11370 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
11380 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
11390 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
113a0 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
113b0 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
113c0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
113d0 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
113e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
113f0 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
11400 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
11410 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
11420 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
11430 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
11440 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
11450 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
11460 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
11470 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
11480 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11490 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
114a0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
114b0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
114c0 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
114d0 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
114e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
114f0 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
11500 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
11510 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
11520 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
11530 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
11540 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
11550 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
11560 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
11570 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
11580 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
11590 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
115a0 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
115b0 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
115c0 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
115d0 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
115e0 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
115f0 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
11600 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
11610 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
11620 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
11630 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
11640 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
11650 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
11660 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
11670 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
11680 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
11690 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
116a0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
116b0 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
116c0 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
116d0 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
116e0 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
116f0 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
11700 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
11710 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
11720 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
11730 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
11740 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
11750 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
11760 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
11770 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
11780 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
11790 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
117a0 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
117b0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
117c0 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
117d0 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
117e0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
117f0 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
11800 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
11810 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
11820 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
11830 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
11840 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
11850 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
11860 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
11870 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
11880 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
11890 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
118a0 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
118b0 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
118c0 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
118d0 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
118e0 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
118f0 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
11900 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
11910 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
11920 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
11930 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
11940 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
11950 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
11960 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
11970 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
11980 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
11990 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
119a0 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
119b0 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
119c0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
119d0 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
119e0 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
119f0 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
11a00 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
11a10 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
11a20 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
11a30 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
11a40 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
11a50 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
11a60 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
11a70 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
11a80 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
11a90 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
11aa0 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
11ab0 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
11ac0 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
11ad0 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
11ae0 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
11af0 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
11b00 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
11b10 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
11b20 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61  ocator.  For exa
11b30 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
11b40 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
11b50 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
11b60 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
11b70 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
11b80 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
11b90 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
11ba0 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
11bb0 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
11bc0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11bd0 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
11be0 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
11bf0 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
11c00 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
11c10 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
11c20 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
11c30 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
11c40 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
11c50 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
11c60 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
11c70 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
11c80 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
11c90 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
11ca0 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
11cb0 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
11cc0 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
11cd0 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
11ce0 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
11cf0 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
11d00 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
11d10 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
11d20 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
11d30 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
11d40 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
11d50 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
11d60 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
11d70 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
11d80 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
11d90 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
11da0 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
11db0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
11dc0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
11dd0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11de0 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
11df0 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
11e00 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
11e10 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
11e20 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
11e30 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
11e40 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
11e50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
11e60 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
11e70 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
11e80 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
11e90 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
11ea0 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
11eb0 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
11ec0 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
11ed0 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
11ee0 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
11ef0 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
11f00 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
11f10 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
11f20 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
11f30 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
11f40 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
11f50 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
11f60 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
11f70 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
11f80 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
11f90 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
11fa0 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
11fb0 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
11fc0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11fd0 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
11fe0 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
11ff0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
12000 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
12010 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
12020 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
12030 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
12040 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
12050 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
12060 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
12070 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
12080 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
12090 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
120a0 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
120b0 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
120c0 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
120d0 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
120e0 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
120f0 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
12100 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
12110 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
12120 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
12130 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
12140 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
12150 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
12160 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
12170 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
12180 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
12190 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
121a0 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
121b0 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
121c0 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
121d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
121e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
121f0 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
12200 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
12210 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
12220 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
12230 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
12240 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
12250 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
12260 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
12270 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
12280 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
12290 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
122a0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
122b0 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
122c0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
122d0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
122e0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
122f0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
12300 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
12310 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
12320 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
12330 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
12340 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
12350 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
12360 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
12370 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
12380 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
12390 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
123a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
123b0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
123c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
123d0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
123e0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
123f0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
12400 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
12410 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
12420 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
12430 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
12440 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
12450 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
12460 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
12470 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
12480 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
12490 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
124a0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
124b0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
124c0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
124d0 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
124e0 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
124f0 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
12500 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
12510 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
12520 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
12530 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
12540 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
12550 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
12560 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
12570 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
12580 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
12590 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
125a0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
125b0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
125c0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
125d0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
125e0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
125f0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
12600 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
12610 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
12620 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
12630 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
12640 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
12650 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
12660 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
12670 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
12680 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
12690 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
126a0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
126b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
126c0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
126d0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
126e0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
126f0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
12700 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
12710 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
12720 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
12730 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
12740 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
12750 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
12760 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
12770 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
12780 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
12790 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
127a0 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
127b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
127c0 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
127d0 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
127e0 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
127f0 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
12800 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
12810 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
12820 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
12830 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
12840 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
12850 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
12860 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
12870 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
12880 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
12890 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
128a0 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
128b0 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
128c0 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
128d0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
128e0 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
128f0 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
12900 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
12910 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
12920 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12930 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
12940 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
12950 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
12960 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
12970 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
12980 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
12990 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
129a0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
129b0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
129c0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
129d0 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
129e0 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
129f0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
12a00 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
12a10 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
12a20 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12a30 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
12a40 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
12a50 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
12a60 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
12a70 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
12a80 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
12a90 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
12aa0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
12ab0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
12ac0 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
12ad0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
12ae0 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
12af0 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
12b00 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
12b10 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
12b20 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
12b30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
12b40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
12b50 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
12b60 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
12b70 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
12b80 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
12b90 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
12ba0 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
12bb0 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
12bc0 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
12bd0 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
12be0 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
12bf0 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
12c00 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
12c10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
12c20 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
12c30 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
12c40 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
12c50 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
12c60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
12c70 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
12c80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
12c90 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
12ca0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
12cb0 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
12cc0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
12cd0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
12ce0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
12cf0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
12d00 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
12d10 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
12d20 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
12d30 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
12d40 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
12d50 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
12d60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
12d70 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
12d80 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
12d90 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
12da0 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
12db0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
12dc0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12dd0 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
12de0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12df0 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
12e00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
12e10 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
12e20 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
12e30 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69  NFIG_MALLOC opti
12e40 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12e50 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12e60 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65   is .** a pointe
12e70 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
12e80 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12e90 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
12ea0 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
12eb0 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
12ec0 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
12ed0 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
12ee0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
12ef0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
12f00 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
12f10 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
12f20 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
12f30 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
12f40 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
12f50 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
12f60 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
12f70 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
12f80 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12f90 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
12fa0 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
12fb0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12fc0 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
12fd0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12fe0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
12ff0 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
13000 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
13010 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
13020 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
13030 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70  FIG_GETMALLOC op
13040 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
13050 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
13060 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
13070 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
13080 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
13090 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
130a0 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
130b0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
130c0 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
130d0 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
130e0 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
130f0 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
13100 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
13110 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
13120 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
13130 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
13140 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
13150 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
13160 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
13170 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
13180 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
13190 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
131a0 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
131b0 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
131c0 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
131d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
131e0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
131f0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13200 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
13210 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
13220 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
13230 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74  MSTATUS option t
13240 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
13250 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
13260 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64  ,.** interpreted
13270 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77   as a boolean, w
13280 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20  hich enables or 
13290 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c  disables the col
132a0 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65  lection of.** me
132b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
132c0 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68  statistics. ^(Wh
132d0 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  en memory alloca
132e0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
132f0 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c  are.** disabled,
13300 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
13310 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
13320 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
13330 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
13340 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
13350 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
13360 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
13370 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
13380 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
13390 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
133a0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
133b0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
133c0 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34 28  qlite3_status64(
133d0 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a  )].**   </ul>)^.
133e0 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ** ^Memory alloc
133f0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
13400 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
13410 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53  default unless S
13420 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
13430 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
13440 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
13450 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20  TUS]=0 in which 
13460 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  case memory.** a
13470 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
13480 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
13490 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
134a0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
134b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
134c0 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATCH]] <dt>SQLIT
134d0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
134e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
134f0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13500 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20  _SCRATCH option 
13510 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
13520 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
13530 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
13540 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61  can use for scra
13550 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54  tch memory.  ^(T
13560 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
13570 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53  rguments.** to S
13580 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
13590 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72  ATCH:  A pointer
135a0 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c   an 8-byte.** al
135b0 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66  igned memory buf
135c0 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74  fer from which t
135d0 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  he scratch alloc
135e0 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a  ations will be.*
135f0 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a  * drawn, the siz
13600 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63  e of each scratc
13610 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a  h allocation (sz
13620 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61  ),.** and the ma
13630 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
13640 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
13650 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68  ons (N).)^.** Th
13660 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
13670 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74   must be a point
13680 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
13690 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a  aligned buffer.*
136a0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  * of at least sz
136b0 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
136c0 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
136d0 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65  ill not use more
136e0 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63   than one scratc
136f0 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68  h buffers per th
13700 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  read..** ^SQLite
13710 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75   will never requ
13720 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62 75  est a scratch bu
13730 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72  ffer that is mor
13740 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65  e than 6.** time
13750 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  s the database p
13760 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  age size..** ^If
13770 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65   SQLite needs ne
13780 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  eds additional.*
13790 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
137a0 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
137b0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
137c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
137d0 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20  ption, then .** 
137e0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
137f0 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  )] will be used 
13800 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65  to obtain the me
13810 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a  mory needed.<p>.
13820 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70  ** ^When the app
13830 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65  lication provide
13840 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20  s any amount of 
13850 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75  scratch memory u
13860 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43  sing.** SQLITE_C
13870 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53  ONFIG_SCRATCH, S
13880 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e  QLite avoids unn
13890 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a  ecessary large.*
138a0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
138b0 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f  c|heap allocatio
138c0 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e  ns]..** This can
138d0 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72   help [Robson pr
138e0 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f  oof|prevent memo
138f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
13900 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68  ilures] due to h
13910 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61  eap.** fragmenta
13920 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f  tion in low-memo
13930 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  ry embedded syst
13940 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ems..** </dd>.**
13950 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13960 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20  FIG_PAGECACHE]] 
13970 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13980 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
13990 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
139a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
139b0 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65  CACHE option spe
139c0 63 69 66 69 65 73 20 61 20 6d 65 6d 6f 72 79 20  cifies a memory 
139d0 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c  pool.** that SQL
139e0 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20  ite can use for 
139f0 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
13a00 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
13a10 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a   default page.**
13a20 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
13a30 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73  ation.  .** This
13a40 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13a50 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70  ption is a no-op
13a60 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
13a70 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a  on-define page.*
13a80 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
13a90 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64  tation is loaded
13aa0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
13ab0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
13ac0 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72  2]..** ^There ar
13ad0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
13ae0 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  s to SQLITE_CONF
13af0 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20  IG_PAGECACHE: A 
13b00 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d  pointer to.** 8-
13b10 62 79 74 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d  byte aligned mem
13b20 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74 68 65 20  ory (pMem), the 
13b30 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67  size of each pag
13b40 65 20 63 61 63 68 65 20 6c 69 6e 65 20 28 73 7a  e cache line (sz
13b50 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75  ),.** and the nu
13b60 6d 62 65 72 20 6f 66 20 63 61 63 68 65 20 6c 69  mber of cache li
13b70 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  nes (N)..** The 
13b80 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
13b90 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
13ba0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
13bb0 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
13bc0 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
13bd0 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 36  etween 512 and 6
13be0 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 20  5536) plus some 
13bf0 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72 20  extra bytes for 
13c00 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61  each.** page hea
13c10 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65  der.  ^The numbe
13c20 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65 73  r of extra bytes
13c30 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20 70   needed by the p
13c40 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61  age header.** ca
13c50 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
13c60 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f  using [SQLITE_CO
13c70 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
13c80 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61  Z]..** ^It is ha
13c90 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72  rmless, apart fr
13ca0 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65  om the wasted me
13cb0 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65  mory,.** for the
13cc0 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f   sz parameter to
13cd0 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
13ce0 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65 20  necessary.  The 
13cf0 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  pMem.** argument
13d00 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
13d10 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
13d20 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  r a pointer to a
13d30 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
13d40 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  ned block of mem
13d50 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ory of at least 
13d60 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68 65  sz*N bytes, othe
13d70 72 77 69 73 65 0a 2a 2a 20 73 75 62 73 65 71 75  rwise.** subsequ
13d80 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73 20  ent behavior is 
13d90 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57  undefined..** ^W
13da0 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20  hen pMem is not 
13db0 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
13dc0 6c 20 73 74 72 69 76 65 20 74 6f 20 75 73 65 20  l strive to use 
13dd0 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
13de0 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66  ded.** to satisf
13df0 79 20 70 61 67 65 20 63 61 63 68 65 20 6e 65 65  y page cache nee
13e00 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b  ds, falling back
13e10 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
13e20 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70  loc()] if.** a p
13e30 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 69  age cache line i
13e40 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20 73 7a  s larger than sz
13e50 20 62 79 74 65 73 20 6f 72 20 69 66 20 61 6c 6c   bytes or if all
13e60 20 6f 66 20 74 68 65 20 70 4d 65 6d 20 62 75 66   of the pMem buf
13e70 66 65 72 0a 2a 2a 20 69 73 20 65 78 68 61 75 73  fer.** is exhaus
13e80 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d  ted..** ^If pMem
13e90 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69   is NULL and N i
13ea0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
13eb0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
13ec0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65  onnection.** doe
13ed0 73 20 61 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c  s an initial bul
13ee0 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  k allocation for
13ef0 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
13f00 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ry.** from [sqli
13f10 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75  te3_malloc()] su
13f20 66 66 69 63 69 65 6e 74 20 66 6f 72 20 4e 20 63  fficient for N c
13f30 61 63 68 65 20 6c 69 6e 65 73 20 69 66 20 4e 20  ache lines if N 
13f40 69 73 20 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a  is positive or.*
13f50 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79 74  * of -1024*N byt
13f60 65 73 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74  es if N is negat
13f70 69 76 65 2c 20 2e 20 5e 49 66 20 61 64 64 69 74  ive, . ^If addit
13f80 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
13f90 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
13fa0 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
13fb0 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
13fc0 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61  the initial.** a
13fd0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
13fe0 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
13ff0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14000 5d 20 73 65 70 61 72 61 74 65 6c 79 20 66 6f 72  ] separately for
14010 20 65 61 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f   each.** additio
14020 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e 20  nal cache line. 
14030 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14040 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
14050 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14060 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a  NFIG_HEAP</dt>.*
14070 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
14080 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f  TE_CONFIG_HEAP o
14090 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
140a0 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
140b0 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20  buffer .** that 
140c0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
140d0 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
140e0 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c  ynamic memory al
140f0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a  location needs.*
14100 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  * beyond those p
14110 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b  rovided for by [
14120 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
14130 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53  RATCH] and.** [S
14140 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
14150 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65  ECACHE]..** ^The
14160 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
14170 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  EAP option is on
14180 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
14190 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
141a0 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65  ed.** with eithe
141b0 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
141c0 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51  _MEMSYS3] or [SQ
141d0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
141e0 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73  YS5] and returns
141f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
14200 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74  R] if invoked ot
14210 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65  herwise..** ^The
14220 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
14230 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45  uments to SQLITE
14240 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a  _CONFIG_HEAP:.**
14250 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   An 8-byte align
14260 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  ed pointer to th
14270 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65  e memory,.** the
14280 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
14290 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62   in the memory b
142a0 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d  uffer, and the m
142b0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
142c0 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74  n size..** ^If t
142d0 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
142e0 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
142f0 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74  nter) is NULL, t
14300 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72  hen SQLite rever
14310 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69  ts.** to using i
14320 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  ts default memor
14330 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65  y allocator (the
14340 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
14350 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29   implementation)
14360 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79  ,.** undoing any
14370 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f   prior invocatio
14380 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  n of [SQLITE_CON
14390 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49  FIG_MALLOC].  ^I
143a0 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  f the.** memory 
143b0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
143c0 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74  ULL then the alt
143d0 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a  ernative memory.
143e0 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ** allocator is 
143f0 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c  engaged to handl
14400 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73  e all of SQLites
14410 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14420 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65  on needs..** The
14430 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
14440 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
14450 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67  er) must be alig
14460 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
14470 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  .** boundary or 
14480 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
14490 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ior of SQLite wi
144a0 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
144b0 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20  .** The minimum 
144c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
144d0 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a  is capped at 2**
144e0 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76  12. Reasonable v
144f0 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65  alues.** for the
14500 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
14510 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a  ion size are 2**
14520 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c  5 through 2**8.<
14530 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14540 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
14550 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14560 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
14570 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
14580 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
14590 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  X option takes a
145a0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
145b0 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70   which is a.** p
145c0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
145d0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
145e0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
145f0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
14600 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
14610 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e  specifies altern
14620 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
14630 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
14640 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20  o be used.** in 
14650 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78 20  place the mutex 
14660 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
14670 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e  nto SQLite.)^  ^
14680 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
14690 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
146a0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
146b0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
146c0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62  ods] structure b
146d0 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74  efore the call t
146e0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
146f0 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e  nfig()] returns.
14700 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
14710 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
14720 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
14730 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
14740 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
14750 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14760 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
14770 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
14780 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
14790 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
147a0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
147b0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
147c0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
147d0 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
147e0 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  G_MUTEX configur
147f0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
14800 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
14810 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
14820 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14830 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d  CONFIG_GETMUTEX]
14840 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14850 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
14860 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
14870 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14880 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61  TMUTEX option ta
14890 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
148a0 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
148b0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
148c0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
148d0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
148e0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
148f0 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ure.  The.** [sq
14900 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
14910 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
14920 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
14930 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
14940 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75  efined mutex rou
14950 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
14960 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
14970 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
14980 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
14990 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
149a0 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
149b0 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
149c0 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
149d0 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
149e0 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
149f0 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
14a00 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51  xample.   ^If SQ
14a10 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
14a20 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
14a30 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
14a40 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
14a50 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
14a60 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
14a70 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
14a80 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
14a90 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
14aa0 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
14ab0 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
14ac0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
14ad0 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
14ae0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
14af0 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
14b00 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
14b10 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
14b20 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
14b30 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14b40 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c  IG_LOOKASIDE]] <
14b50 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14b60 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
14b70 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
14b80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
14b90 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b  ASIDE option tak
14ba0 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
14bb0 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a   that determine.
14bc0 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 73  ** the default s
14bd0 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65  ize of lookaside
14be0 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20   memory on each 
14bf0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
14c00 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69  tion]..** The fi
14c10 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
14c20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
14c30 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
14c40 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
14c50 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20  e second is the 
14c60 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
14c70 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20  ts allocated to 
14c80 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
14c90 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53  nnection.)^  ^(S
14ca0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
14cb0 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74  KASIDE.** sets t
14cc0 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69  he <i>default</i
14cd0 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65  > lookaside size
14ce0 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42  . The [SQLITE_DB
14cf0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14d00 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b  ].** option to [
14d10 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
14d20 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64  g()] can be used
14d30 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
14d40 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66  ookaside.** conf
14d50 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  iguration on ind
14d60 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69  ividual connecti
14d70 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ons.)^ </dd>.**.
14d80 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14d90 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  IG_PCACHE2]] <dt
14da0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
14db0 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c  CACHE2</dt>.** <
14dc0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
14dd0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
14de0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14df0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
14e00 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f  hich is .** a po
14e10 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c  inter to an [sql
14e20 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
14e30 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54  ods2] object.  T
14e40 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69  his object speci
14e50 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65  fies.** the inte
14e60 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f  rface to a custo
14e70 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  m page cache imp
14e80 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a  lementation.)^.*
14e90 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  * ^SQLite makes 
14ea0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
14eb0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
14ec0 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c  thods2] object.<
14ed0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14ee0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14ef0 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
14f00 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
14f10 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
14f20 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
14f30 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
14f40 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
14f50 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14f60 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
14f70 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c  inter to an [sql
14f80 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
14f90 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53  ods2] object.  S
14fa0 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a  QLite copies of.
14fb0 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20 70  ** the current p
14fc0 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
14fd0 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68  entation into th
14fe0 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64  at object.)^ </d
14ff0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15000 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c  E_CONFIG_LOG]] <
15010 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15020 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _LOG</dt>.** <dd
15030 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  > The SQLITE_CON
15040 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69  FIG_LOG option i
15050 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
15060 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a  ure the SQLite.*
15070 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20  * global [error 
15080 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53  log]..** (^The S
15090 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
150a0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
150b0 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70  o arguments: a p
150c0 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66  ointer to a.** f
150d0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63  unction with a c
150e0 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66  all signature of
150f0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69   void(*)(void*,i
15100 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  nt,const char*),
15110 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74   .** and a point
15120 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20  er to void. ^If 
15130 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
15140 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
15150 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b  , it is.** invok
15160 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
15170 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73  og()] to process
15180 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76   each logging ev
15190 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
151a0 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
151b0 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b  r is NULL, the [
151c0 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69  sqlite3_log()] i
151d0 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73  nterface becomes
151e0 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68   a no-op..** ^Th
151f0 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74  e void pointer t
15200 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e  hat is the secon
15210 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51  d argument to SQ
15220 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
15230 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72  is.** passed thr
15240 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
15250 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
15260 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
15270 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
15280 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76   function whenev
15290 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  er that function
152a0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54   is invoked.  ^T
152b0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
152c0 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f  ter to.** the lo
152d0 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73  gger function is
152e0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
152f0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
15300 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
15310 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
15320 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20  log()] call and 
15330 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62  is intended to b
15340 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  e a [result code
15350 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65  ] or an.** [exte
15360 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
15370 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70  ].  ^The third p
15380 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
15390 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73  to the logger is
153a0 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20  .** log message 
153b0 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67  after formatting
153c0 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e   via [sqlite3_sn
153d0 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68  printf()]..** Th
153e0 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67  e SQLite logging
153f0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
15400 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65  t reentrant; the
15410 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
15420 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20  .** supplied by 
15430 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
15440 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20  must not invoke 
15450 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
15460 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75  face..** In a mu
15470 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70  lti-threaded app
15480 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70  lication, the ap
15490 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
154a0 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
154b0 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72  tion must be thr
154c0 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a  eadsafe. </dd>.*
154d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
154e0 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53  NFIG_URI]] <dt>S
154f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
15500 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51  .** <dd>^(The SQ
15510 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
15520 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15530 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
15540 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49  f type int..** I
15550 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  f non-zero, then
15560 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
15570 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65   globally enable
15580 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65  d. If the parame
15590 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20  ter is zero,.** 
155a0 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
155b0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  g is globally di
155c0 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52  sabled.)^ ^If UR
155d0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
155e0 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65  obally.** enable
155f0 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73  d, all filenames
15600 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
15610 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
15620 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
15630 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ,.** [sqlite3_op
15640 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70  en16()] or.** sp
15650 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20  ecified as part 
15660 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d  of [ATTACH] comm
15670 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72  ands are interpr
15680 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65  eted as URIs, re
15690 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77  gardless.** of w
156a0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
156b0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
156c0 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  RI] flag is set 
156d0 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
156e0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
156f0 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69  is opened. ^If i
15700 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  t is globally di
15710 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65  sabled, filename
15720 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e  s are.** only in
15730 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
15740 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f  s if the SQLITE_
15750 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73  OPEN_URI flag is
15760 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a   set when the.**
15770 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15780 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
15790 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52  ^(By default, UR
157a0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
157b0 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c  obally.** disabl
157c0 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20  ed. The default 
157d0 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61  value may be cha
157e0 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e  nged by compilin
157f0 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  g with the.** [S
15800 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73  QLITE_USE_URI] s
15810 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e  ymbol defined.)^
15820 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15830 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
15840 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74  INDEX_SCAN]] <dt
15850 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  >SQLITE_CONFIG_C
15860 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
15870 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  AN.** <dd>^The S
15880 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
15890 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
158a0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
158b0 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a  single integer.*
158c0 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  * argument which
158d0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
158e0 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20  as a boolean in 
158f0 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20  order to enable 
15900 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68  or disable.** th
15910 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
15920 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75  g indices for fu
15930 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69  ll table scans i
15940 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69  n the query opti
15950 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64  mizer..** ^The d
15960 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69  efault setting i
15970 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20  s determined.** 
15980 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41  by the [SQLITE_A
15990 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  LLOW_COVERING_IN
159a0 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c  DEX_SCAN] compil
159b0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f  e-time option, o
159c0 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20  r is "on".** if 
159d0 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  that compile-tim
159e0 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74  e option is omit
159f0 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c  ted..** The abil
15a00 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74  ity to disable t
15a10 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
15a20 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
15a30 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a  ull table scans.
15a40 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f  ** is because so
15a50 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63  me incorrectly c
15a60 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c  oded legacy appl
15a70 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d  ications might m
15a80 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68  alfunction.** wh
15a90 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74  en the optimizat
15aa0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20  ion is enabled. 
15ab0 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61   Providing the a
15ac0 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73  bility to.** dis
15ad0 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a  able the optimiz
15ae0 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65  ation allows the
15af0 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70   older, buggy ap
15b00 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74  plication code t
15b10 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75  o work.** withou
15b20 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69  t change even wi
15b30 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  th newer version
15b40 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
15b50 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15b60 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51  IG_PCACHE]] [[SQ
15b70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15b80 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  CACHE]].** <dt>S
15b90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
15ba0 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43  CHE and SQLITE_C
15bb0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a  ONFIG_GETPCACHE.
15bc0 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70  ** <dd> These op
15bd0 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65  tions are obsole
15be0 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f  te and should no
15bf0 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77  t be used by new
15c00 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61   code..** They a
15c10 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  re retained for 
15c20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
15c30 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20  ibility but are 
15c40 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c  now no-ops..** <
15c50 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
15c60 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
15c70 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  G]].** <dt>SQLIT
15c80 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a  E_CONFIG_SQLLOG.
15c90 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
15ca0 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
15cb0 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69  able if sqlite i
15cc0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
15cd0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
15ce0 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72  NABLE_SQLLOG] pr
15cf0 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  e-processor macr
15d00 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66  o defined. The f
15d10 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68  irst argument sh
15d20 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69  ould.** be a poi
15d30 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69  nter to a functi
15d40 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28  on of type void(
15d50 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
15d60 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  *,const char*, i
15d70 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  nt)..** The seco
15d80 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20  nd should be of 
15d90 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68  type (void*). Th
15da0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
15db0 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62  voked by the lib
15dc0 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65  rary.** in three
15dd0 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d   separate circum
15de0 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66  stances, identif
15df0 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65  ied by the value
15e00 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a   passed as the.*
15e10 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
15e20 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74  er. If the fourt
15e30 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30  h parameter is 0
15e40 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
15e50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
15e60 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  * passed as the 
15e70 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
15e80 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70  has just been op
15e90 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20  ened. The third 
15ea0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e  argument.** poin
15eb0 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63  ts to a buffer c
15ec0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61  ontaining the na
15ed0 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64  me of the main d
15ee0 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66  atabase file. If
15ef0 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
15f00 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74  arameter is 1, t
15f10 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
15f20 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74  ement that the t
15f30 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  hird parameter.*
15f40 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20  * points to has 
15f50 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74  just been execut
15f60 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66  ed. Or, if the f
15f70 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
15f80 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  is 2, then.** th
15f90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69  e connection bei
15fa0 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ng passed as the
15fb0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
15fc0 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65  r is being close
15fd0 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20  d. The.** third 
15fe0 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73  parameter is pas
15ff0 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73  sed NULL In this
16000 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70   case.  An examp
16010 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73  le of using this
16020 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
16030 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  n option can be 
16040 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73  seen in the "tes
16050 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72  t_sqllog.c" sour
16060 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68  ce file in.** th
16070 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69  e canonical SQLi
16080 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c  te source tree.<
16090 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
160a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
160b0 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  SIZE]].** <dt>SQ
160c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
160d0 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51  _SIZE.** <dd>^SQ
160e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
160f0 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20  _SIZE takes two 
16100 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28  64-bit integer (
16110 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76  sqlite3_int64) v
16120 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72  alues.** that ar
16130 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d  e the default mm
16140 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74  ap size limit (t
16150 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
16160 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d  ng for.** [PRAGM
16170 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e  A mmap_size]) an
16180 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c  d the maximum al
16190 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20  lowed mmap size 
161a0 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64  limit..** ^The d
161b0 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63  efault setting c
161c0 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  an be overridden
161d0 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61 73   by each databas
161e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69  e connection usi
161f0 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65  ng.** either the
16200 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
16210 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20  ze] command, or 
16220 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  by using the.** 
16230 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
16240 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f  AP_SIZE] file co
16250 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61  ntrol.  ^(The ma
16260 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d  ximum allowed mm
16270 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20  ap size.** will 
16280 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  be silently trun
16290 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73 61  cated if necessa
162a0 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f  ry so that it do
162b0 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68  es not exceed th
162c0 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  e.** compile-tim
162d0 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73  e maximum mmap s
162e0 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a  ize set by the.*
162f0 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d  * [SQLITE_MAX_MM
16300 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65  AP_SIZE] compile
16310 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a  -time option.)^.
16320 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61 72  ** ^If either ar
16330 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f  gument to this o
16340 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76  ption is negativ
16350 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72 67  e, then that arg
16360 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e  ument is.** chan
16370 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69  ged to its compi
16380 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e  le-time default.
16390 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
163a0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
163b0 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  PSIZE]].** <dt>S
163c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
163d0 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c  32_HEAPSIZE.** <
163e0 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
163f0 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
16400 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f  SIZE option is o
16410 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
16420 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f   SQLite is.** co
16430 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f  mpiled for Windo
16440 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ws with the [SQL
16450 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43  ITE_WIN32_MALLOC
16460 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
16470 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64  macro.** defined
16480 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  . ^SQLITE_CONFIG
16490 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
164a0 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75  takes a 32-bit u
164b0 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
164c0 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70  value.** that sp
164d0 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 69  ecifies the maxi
164e0 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20  mum size of the 
164f0 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a  created heap..**
16500 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16510 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
16520 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
16530 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
16540 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  DRSZ.** <dd>^The
16550 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16560 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69  CACHE_HDRSZ opti
16570 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
16580 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
16590 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
165a0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
165b0 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20  and writes into 
165c0 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68 65  that integer the
165d0 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61   number of extra
165e0 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70 61  .** bytes per pa
165f0 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 20  ge required for 
16600 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51  each page in [SQ
16610 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
16620 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61  CACHE]..** The a
16630 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73  mount of extra s
16640 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63 61  pace required ca
16650 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69  n change dependi
16660 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ng on the compil
16670 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c  er,.** target pl
16680 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69  atform, and SQLi
16690 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  te version..**.*
166a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
166b0 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74  G_PMASZ]].** <dt
166c0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
166d0 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  MASZ.** <dd>^The
166e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
166f0 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65  MASZ option take
16700 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
16710 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  eter which.** is
16720 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74   an unsigned int
16730 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74 68  eger and sets th
16740 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53  e "Minimum PMA S
16750 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c  ize" for the mul
16760 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f  tithreaded.** so
16770 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74  rter to that int
16780 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61 75  eger.  The defau
16790 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53  lt minimum PMA S
167a0 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74 68  ize is set by th
167b0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52  e.** [SQLITE_SOR
167c0 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69  TER_PMASZ] compi
167d0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20  le-time option. 
167e0 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72 65   New threads are
167f0 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20   launched.** to 
16800 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f  help with sort o
16810 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d  perations when m
16820 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f 72  ultithreaded sor
16830 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c  ting.** is enabl
16840 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50  ed (using the [P
16850 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63  RAGMA threads] c
16860 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20  ommand) and the 
16870 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e  amount of conten
16880 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65  t.** to be sorte
16890 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70 61  d exceeds the pa
168a0 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68  ge size times th
168b0 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65  e minimum of the
168c0 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68  .** [PRAGMA cach
168d0 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20  e_size] setting 
168e0 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a  and this value..
168f0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16900 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53  ONFIG_STMTJRNL_S
16910 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  PILL]].** <dt>SQ
16920 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
16930 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64  JRNL_SPILL.** <d
16940 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
16950 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  NFIG_STMTJRNL_SP
16960 49 4c 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  ILL option takes
16970 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
16980 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 62 65 63  ter which.** bec
16990 6f 6d 65 73 20 74 68 65 20 5b 73 74 61 74 65 6d  omes the [statem
169a0 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69  ent journal] spi
169b0 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65 73  ll-to-disk thres
169c0 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74  hold.  .** [Stat
169d0 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20  ement journals] 
169e0 61 72 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f  are held in memo
169f0 72 79 20 75 6e 74 69 6c 20 74 68 65 69 72 20 73  ry until their s
16a00 69 7a 65 20 28 69 6e 20 62 79 74 65 73 29 0a 2a  ize (in bytes).*
16a10 2a 20 65 78 63 65 65 64 73 20 74 68 69 73 20 74  * exceeds this t
16a20 68 72 65 73 68 6f 6c 64 2c 20 61 74 20 77 68 69  hreshold, at whi
16a30 63 68 20 70 6f 69 6e 74 20 74 68 65 79 20 61 72  ch point they ar
16a40 65 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  e written to dis
16a50 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65 20  k..** Or if the 
16a60 74 68 72 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c  threshold is -1,
16a70 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e   statement journ
16a80 61 6c 73 20 61 72 65 20 61 6c 77 61 79 73 20 68  als are always h
16a90 65 6c 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65  eld.** exclusive
16aa0 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  ly in memory..**
16ab0 20 53 69 6e 63 65 20 6d 61 6e 79 20 73 74 61 74   Since many stat
16ac0 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e  ement journals n
16ad0 65 76 65 72 20 62 65 63 6f 6d 65 20 6c 61 72 67  ever become larg
16ae0 65 2c 20 73 65 74 74 69 6e 67 20 74 68 65 20 73  e, setting the s
16af0 70 69 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c  pill.** threshol
16b00 64 20 74 6f 20 61 20 76 61 6c 75 65 20 73 75 63  d to a value suc
16b10 68 20 61 73 20 36 34 4b 69 42 20 63 61 6e 20 67  h as 64KiB can g
16b20 72 65 61 74 6c 79 20 72 65 64 75 63 65 20 74 68  reatly reduce th
16b30 65 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49  e amount of.** I
16b40 2f 4f 20 72 65 71 75 69 72 65 64 20 74 6f 20 73  /O required to s
16b50 75 70 70 6f 72 74 20 73 74 61 74 65 6d 65 6e 74  upport statement
16b60 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   rollback..** Th
16b70 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
16b80 66 6f 72 20 74 68 69 73 20 73 65 74 74 69 6e 67  for this setting
16b90 20 69 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62   is controlled b
16ba0 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
16bb0 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d  _STMTJRNL_SPILL]
16bc0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
16bd0 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  tion..** </dl>.*
16be0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16bf0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
16c00 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
16c10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16c20 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
16c30 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
16c40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16c50 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
16c60 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
16c70 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
16c80 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
16c90 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
16ca0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
16cb0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
16cc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16cd0 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
16ce0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
16cf0 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
16d00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
16d10 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
16d20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
16d30 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
16d40 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16d50 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
16d60 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
16d70 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
16d80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16d90 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
16da0 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
16db0 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
16dc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16dd0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
16de0 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
16df0 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
16e00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
16e10 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
16e20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
16e30 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
16e40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16e50 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
16e60 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
16e70 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
16e80 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
16e90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
16ea0 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
16eb0 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
16ec0 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
16ed0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
16ee0 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
16ef0 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
16f00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16f10 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
16f20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
16f30 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16f40 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
16f50 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
16f60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16f70 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
16f80 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
16f90 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
16fa0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
16fb0 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
16fc0 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
16fd0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16fe0 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
16ff0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
17000 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
17010 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17020 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
17030 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
17040 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
17050 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
17060 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
17070 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
17080 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  20  /* int */.#d
17090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
170a0 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20  FIG_SQLLOG      
170b0 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c   21  /* xSqllog,
170c0 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
170d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
170e0 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20  MMAP_SIZE    22 
170f0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36   /* sqlite3_int6
17100 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  4, sqlite3_int64
17110 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17120 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
17130 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33  HEAPSIZE      23
17140 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
17150 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17160 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
17170 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20  DRSZ        24  
17180 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23  /* int *psz */.#
17190 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
171a0 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20  NFIG_PMASZ      
171b0 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20           25  /* 
171c0 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50  unsigned int szP
171d0 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ma */.#define SQ
171e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
171f0 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20  JRNL_SPILL      
17200 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65  26  /* int nByte
17210 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
17220 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
17230 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75  nnection Configu
17240 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
17250 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
17260 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
17270 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
17280 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
17290 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
172a0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
172b0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
172c0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
172d0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
172e0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
172f0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
17300 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
17310 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
17320 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
17330 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
17340 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
17350 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
17360 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
17370 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
17380 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
17390 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
173a0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
173b0 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
173c0 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
173d0 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54  call worked.  ^T
173e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
173f0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
17400 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
17410 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
17420 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
17430 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
17440 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
17450 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
17460 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
17470 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
17480 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
17490 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
174a0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
174b0 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65  tion takes three
174c0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
174d0 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
174e0 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f  mine the .** [lo
174f0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
17500 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
17510 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  uration for the 
17520 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
17530 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66  tion]..** ^The f
17540 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74  irst argument (t
17550 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
17560 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  er to [sqlite3_d
17570 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61  b_config()] is a
17580 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
17590 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
175a0 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
175b0 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
175c0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
175d0 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
175e0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
175f0 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
17600 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
17610 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
17620 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
17630 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
17640 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
17650 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
17660 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
17670 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
17680 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
17690 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
176a0 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
176b0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
176c0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
176d0 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
176e0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
176f0 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
17700 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
17710 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
17720 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
17730 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
17740 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
17750 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
17760 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
17770 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
17780 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
17790 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
177a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
177b0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
177c0 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
177d0 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
177e0 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
177f0 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
17800 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
17810 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20  maller multiple 
17820 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f  of 8.  ^(The loo
17830 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a  kaside memory.**
17840 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
17850 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
17860 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c  nnection can onl
17870 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65  y be changed whe
17880 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63  n that.** connec
17890 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72  tion is not curr
178a0 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b  ently using look
178b0 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72  aside memory, or
178c0 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a   in other words.
178d0 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72  ** when the "cur
178e0 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75  rent value" retu
178f0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
17900 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44  te3_db_status](D
17910 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ,[SQLITE_CONFIG_
17920 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20  LOOKASIDE],...) 
17930 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20  is zero..** Any 
17940 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67  attempt to chang
17950 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  e the lookaside 
17960 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61  memory configura
17970 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73  tion when lookas
17980 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73  ide.** memory is
17990 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74   in use leaves t
179a0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
179b0 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72   unchanged and r
179c0 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
179d0 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e  TE_BUSY].)^</dd>
179e0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
179f0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
17a00 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_FKEY</dt>.** <
17a10 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
17a20 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
17a30 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
17a40 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66  e enforcement of
17a50 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
17a60 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20   constraints].  
17a70 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
17a80 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
17a90 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
17aa0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
17ab0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
17ac0 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
17ad0 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
17ae0 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  nt,.** positive 
17af0 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66  to enable FK enf
17b00 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61  orcement or nega
17b10 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b  tive to leave FK
17b20 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20   enforcement.** 
17b30 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
17b40 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17b50 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
17b60 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
17b70 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
17b80 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
17b90 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
17ba0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69  FK enforcement i
17bb0 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66  s off or on.** f
17bc0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
17bd0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
17be0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
17bf0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
17c00 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
17c10 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65  e the FK enforce
17c20 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20  ment setting is 
17c30 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
17c40 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
17c50 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
17c60 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
17c70 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
17c80 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
17c90 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
17ca0 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45   disable [CREATE
17cb0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
17cc0 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  ers]..** There s
17cd0 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
17ce0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
17cf0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
17d00 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
17d10 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
17d20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69  0 to disable tri
17d30 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69  ggers,.** positi
17d40 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69  ve to enable tri
17d50 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76  ggers or negativ
17d60 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
17d70 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
17d80 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
17d90 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
17da0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
17db0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
17dc0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
17dd0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
17de0 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72   whether trigger
17df0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f  s are disabled o
17e00 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
17e10 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
17e20 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
17e30 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
17e40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
17e50 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
17e60 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74  the trigger sett
17e70 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
17e80 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
17e90 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
17ea0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
17eb0 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c  _FTS3_TOKENIZER<
17ec0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
17ed0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
17ee0 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
17ef0 69 73 61 62 6c 65 20 74 68 65 20 74 77 6f 2d 61  isable the two-a
17f00 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 69  rgument.** versi
17f10 6f 6e 20 6f 66 20 74 68 65 20 5b 66 74 73 33 5f  on of the [fts3_
17f20 74 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75 6e  tokenizer()] fun
17f30 63 74 69 6f 6e 20 77 68 69 63 68 20 69 73 20 70  ction which is p
17f40 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 46  art of the.** [F
17f50 54 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20 73  TS3] full-text s
17f60 65 61 72 63 68 20 65 6e 67 69 6e 65 20 65 78 74  earch engine ext
17f70 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65  ension..** There
17f80 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
17f90 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
17fa0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
17fb0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
17fc0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
17fd0 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 66  s 0 to disable f
17fe0 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20  ts3_tokenizer() 
17ff0 6f 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  or.** positive t
18000 6f 20 65 6e 61 62 6c 65 20 66 74 73 33 5f 74 6f  o enable fts3_to
18010 6b 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65 67  kenizer() or neg
18020 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
18030 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e  he setting.** un
18040 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
18050 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18060 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
18070 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
18080 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
18090 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
180a0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
180b0 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 69  fts3_tokenizer i
180c0 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  s disabled or en
180d0 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  abled.** followi
180e0 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
180f0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18100 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
18110 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
18120 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
18130 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e  new setting is n
18140 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
18150 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
18160 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
18170 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58  G_ENABLE_LOAD_EX
18180 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20  TENSION</dt>.** 
18190 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
181a0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
181b0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
181c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64  he [sqlite3_load
181d0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a  _extension()].**
181e0 20 69 6e 74 65 72 66 61 63 65 20 69 6e 64 65 70   interface indep
181f0 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68 65 20  endently of the 
18200 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  [load_extension(
18210 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  )] SQL function.
18220 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
18230 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
18240 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20 65 6e  ension()] API en
18250 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
18260 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43 2d  s both the.** C-
18270 41 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  API [sqlite3_loa
18280 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 61  d_extension()] a
18290 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nd the SQL funct
182a0 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73  ion [load_extens
182b0 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72 65  ion()]..** There
182c0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
182d0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
182e0 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 65  nts..** When the
182f0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
18300 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  to this interfac
18310 65 20 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e 6c  e is 1, then onl
18320 79 20 74 68 65 20 43 2d 41 50 49 20 69 73 0a 2a  y the C-API is.*
18330 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 74 68  * enabled and th
18340 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
18350 65 6d 61 69 6e 73 20 64 69 73 61 62 6c 65 64 2e  emains disabled.
18360 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20 61    If the first a
18370 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
18380 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
18390 30 2c 20 74 68 65 6e 20 62 6f 74 68 20 74 68 65  0, then both the
183a0 20 43 2d 41 50 49 20 61 6e 64 20 74 68 65 20 53   C-API and the S
183b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  QL function are 
183c0 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66 20  disabled..** If 
183d0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
183e0 6e 74 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 6e  nt is -1, then n
183f0 6f 20 63 68 61 6e 67 65 73 20 61 72 65 20 6d 61  o changes are ma
18400 64 65 20 74 6f 20 73 74 61 74 65 20 6f 66 20 65  de to state of e
18410 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d 41  ither the.** C-A
18420 50 49 20 6f 72 20 74 68 65 20 53 51 4c 20 66 75  PI or the SQL fu
18430 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73  nction..** The s
18440 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18450 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
18460 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
18470 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
18480 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
18490 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 5b  dicate whether [
184a0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
184b0 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66  ension()] interf
184c0 61 63 65 0a 2a 2a 20 69 73 20 64 69 73 61 62 6c  ace.** is disabl
184d0 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 20 66 6f  ed or enabled fo
184e0 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
184f0 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
18500 61 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a 20  arameter may.** 
18510 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
18520 72 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  r, in which case
18530 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67   the new setting
18540 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
18550 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a   back..** </dd>.
18560 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
18570 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42  _DBCONFIG_MAINDB
18580 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NAME</dt>.** <dd
18590 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
185a0 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  s used to change
185b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
185c0 20 22 6d 61 69 6e 22 20 64 61 74 61 62 61 73 65   "main" database
185d0 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e 54 68  .** schema.  ^Th
185e0 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e 74 20  e sole argument 
185f0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
18600 61 20 63 6f 6e 73 74 61 6e 74 20 55 54 46 38 20  a constant UTF8 
18610 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63 68 20  string.** which 
18620 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20  will become the 
18630 6e 65 77 20 73 63 68 65 6d 61 20 6e 61 6d 65 20  new schema name 
18640 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d 61 69  in place of "mai
18650 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20  n".  ^SQLite.** 
18660 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20 61 20  does not make a 
18670 63 6f 70 79 20 6f 66 20 74 68 65 20 6e 65 77 20  copy of the new 
18680 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e 61 6d 65  main schema name
18690 20 73 74 72 69 6e 67 2c 20 73 6f 20 74 68 65 20   string, so the 
186a0 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d  application.** m
186b0 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20  ust ensure that 
186c0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 61 73  the argument pas
186d0 73 65 64 20 69 6e 74 6f 20 74 68 69 73 20 44 42  sed into this DB
186e0 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20 69 73  CONFIG option is
186f0 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 75 6e   unchanged.** un
18700 74 69 6c 20 61 66 74 65 72 20 74 68 65 20 64 61  til after the da
18710 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18720 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f 64  n closes..** </d
18730 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18740 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f  ITE_DBCONFIG_NO_
18750 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64  CKPT_ON_CLOSE</d
18760 74 3e 0a 2a 2a 20 3c 64 64 3e 20 55 73 75 61 6c  t>.** <dd> Usual
18770 6c 79 2c 20 77 68 65 6e 20 61 20 64 61 74 61 62  ly, when a datab
18780 61 73 65 20 69 6e 20 77 61 6c 20 6d 6f 64 65 20  ase in wal mode 
18790 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 64 65 74  is closed or det
187a0 61 63 68 65 64 20 66 72 6f 6d 20 61 20 0a 2a 2a  ached from a .**
187b0 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
187c0 2c 20 53 51 4c 69 74 65 20 63 68 65 63 6b 73 20  , SQLite checks 
187d0 69 66 20 74 68 69 73 20 77 69 6c 6c 20 6d 65 61  if this will mea
187e0 6e 20 74 68 61 74 20 74 68 65 72 65 20 61 72 65  n that there are
187f0 20 6e 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e   now no .** conn
18800 65 63 74 69 6f 6e 73 20 61 74 20 61 6c 6c 20 74  ections at all t
18810 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  o the database. 
18820 49 66 20 73 6f 2c 20 69 74 20 70 65 72 66 6f 72  If so, it perfor
18830 6d 73 20 61 20 63 68 65 63 6b 70 6f 69 6e 74 20  ms a checkpoint 
18840 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 62 65  .** operation be
18850 66 6f 72 65 20 63 6c 6f 73 69 6e 67 20 74 68 65  fore closing the
18860 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68 69   connection. Thi
18870 73 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65 20  s option may be 
18880 75 73 65 64 20 74 6f 0a 2a 2a 20 6f 76 65 72 72  used to.** overr
18890 69 64 65 20 74 68 69 73 20 62 65 68 61 76 69 6f  ide this behavio
188a0 75 72 2e 20 54 68 65 20 66 69 72 73 74 20 70 61  ur. The first pa
188b0 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74  rameter passed t
188c0 6f 20 74 68 69 73 20 6f 70 65 72 61 74 69 6f 6e  o this operation
188d0 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65  .** is an intege
188e0 72 20 2d 20 6e 6f 6e 2d 7a 65 72 6f 20 74 6f 20  r - non-zero to 
188f0 64 69 73 61 62 6c 65 20 63 68 65 63 6b 70 6f 69  disable checkpoi
18900 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72  nts-on-close, or
18910 20 7a 65 72 6f 20 28 74 68 65 0a 2a 2a 20 64 65   zero (the.** de
18920 66 61 75 6c 74 29 20 74 6f 20 65 6e 61 62 6c 65  fault) to enable
18930 20 74 68 65 6d 2e 20 54 68 65 20 73 65 63 6f 6e   them. The secon
18940 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
18950 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
18960 6e 74 65 67 65 72 0a 2a 2a 20 69 6e 74 6f 20 77  nteger.** into w
18970 68 69 63 68 20 69 73 20 77 72 69 74 74 65 6e 20  hich is written 
18980 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
18990 74 65 20 77 68 65 74 68 65 72 20 63 68 65 63 6b  te whether check
189a0 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a  points-on-close.
189b0 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 64 69 73  ** have been dis
189c0 61 62 6c 65 64 20 2d 20 30 20 69 66 20 74 68 65  abled - 0 if the
189d0 79 20 61 72 65 20 6e 6f 74 20 64 69 73 61 62 6c  y are not disabl
189e0 65 64 2c 20 31 20 69 66 20 74 68 65 79 20 61 72  ed, 1 if they ar
189f0 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  e..** </dd>.**.*
18a00 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
18a10 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53  ONFIG_ENABLE_QPS
18a20 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 28  G</dt>.** <dd>^(
18a30 54 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  The SQLITE_DBCON
18a40 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20  FIG_ENABLE_QPSG 
18a50 6f 70 74 69 6f 6e 20 61 63 74 69 76 61 74 65 73  option activates
18a60 20 6f 72 20 64 65 61 63 74 69 76 61 74 65 73 0a   or deactivates.
18a70 2a 2a 20 74 68 65 20 5b 71 75 65 72 79 20 70 6c  ** the [query pl
18a80 61 6e 6e 65 72 20 73 74 61 62 69 6c 69 74 79 20  anner stability 
18a90 67 75 61 72 61 6e 74 65 65 5d 20 28 51 50 53 47  guarantee] (QPSG
18aa0 29 2e 20 20 57 68 65 6e 20 74 68 65 20 51 50 53  ).  When the QPS
18ab0 47 20 69 73 20 61 63 74 69 76 65 2c 0a 2a 2a 20  G is active,.** 
18ac0 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 71 75 65  a single SQL que
18ad0 72 79 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  ry statement wil
18ae0 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 65  l always use the
18af0 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
18b00 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66  regardless.** of
18b10 20 76 61 6c 75 65 73 20 6f 66 20 5b 62 6f 75 6e   values of [boun
18b20 64 20 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e  d parameters].)^
18b30 20 54 68 65 20 51 50 53 47 20 64 69 73 61 62 6c   The QPSG disabl
18b40 65 73 20 73 6f 6d 65 20 71 75 65 72 79 20 6f 70  es some query op
18b50 74 69 6d 69 7a 61 74 69 6f 6e 73 0a 2a 2a 20 74  timizations.** t
18b60 68 61 74 20 6c 6f 6f 6b 20 61 74 20 74 68 65 20  hat look at the 
18b70 76 61 6c 75 65 73 20 6f 66 20 62 6f 75 6e 64 20  values of bound 
18b80 70 61 72 61 6d 65 74 65 72 73 2c 20 77 68 69 63  parameters, whic
18b90 68 20 63 61 6e 20 6d 61 6b 65 20 73 6f 6d 65 20  h can make some 
18ba0 71 75 65 72 69 65 73 0a 2a 2a 20 73 6c 6f 77 65  queries.** slowe
18bb0 72 2e 20 20 42 75 74 20 74 68 65 20 51 50 53 47  r.  But the QPSG
18bc0 20 68 61 73 20 74 68 65 20 61 64 76 61 6e 74 61   has the advanta
18bd0 67 65 20 6f 66 20 6d 6f 72 65 20 70 72 65 64 69  ge of more predi
18be0 63 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e  ctable behavior.
18bf0 20 20 57 69 74 68 0a 2a 2a 20 74 68 65 20 51 50    With.** the QP
18c00 53 47 20 61 63 74 69 76 65 2c 20 53 51 4c 69 74  SG active, SQLit
18c10 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 75 73  e will always us
18c20 65 20 74 68 65 20 73 61 6d 65 20 71 75 65 72 79  e the same query
18c30 20 70 6c 61 6e 20 69 6e 20 74 68 65 20 66 69 65   plan in the fie
18c40 6c 64 20 61 73 0a 2a 2a 20 77 61 73 20 75 73 65  ld as.** was use
18c50 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
18c60 20 69 6e 20 74 68 65 20 6c 61 62 2e 0a 2a 2a 20   in the lab..** 
18c70 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
18c80 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
18c90 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49  ITE_DBCONFIG_MAI
18ca0 4e 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20  NDBNAME         
18cb0 20 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74     1000 /* const
18cc0 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e   char* */.#defin
18cd0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
18ce0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20  G_LOOKASIDE     
18cf0 20 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20          1001 /* 
18d00 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
18d10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18d20 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
18d30 46 4b 45 59 20 20 20 20 20 20 20 20 20 20 20 31  FKEY           1
18d40 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  002 /* int int* 
18d50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18d60 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
18d70 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
18d80 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74   1003 /* int int
18d90 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
18da0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
18db0 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a  BLE_FTS3_TOKENIZ
18dc0 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69  ER 1004 /* int i
18dd0 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
18de0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
18df0 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e  NABLE_LOAD_EXTEN
18e00 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74  SION 1005 /* int
18e10 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
18e20 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
18e30 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53  _NO_CKPT_ON_CLOS
18e40 45 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20 69  E      1006 /* i
18e50 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
18e60 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
18e70 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 20  IG_ENABLE_QPSG  
18e80 20 20 20 20 20 20 20 20 20 31 30 30 37 20 2f 2a           1007 /*
18e90 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f   int int* */.../
18ea0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
18eb0 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
18ec0 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
18ed0 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44   Codes.** METHOD
18ee0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
18ef0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
18f00 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
18f10 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61  es() routine ena
18f20 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
18f30 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65   the.** [extende
18f40 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
18f50 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74  feature of SQLit
18f60 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64  e. ^The extended
18f70 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73   result.** codes
18f80 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
18f90 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73   default for his
18fa0 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62  torical compatib
18fb0 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ility..*/.int sq
18fc0 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
18fd0 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
18fe0 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
18ff0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19000 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
19010 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  owid.** METHOD: 
19020 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45  sqlite3.**.** ^E
19030 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73  ach entry in mos
19040 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20  t SQLite tables 
19050 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54  (except for [WIT
19060 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c  HOUT ROWID] tabl
19070 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69  es).** has a uni
19080 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  que 64-bit signe
19090 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79  d.** integer key
190a0 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57   called the [ROW
190b0 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e  ID | "rowid"]. ^
190c0 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77  The rowid is alw
190d0 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a  ays available.**
190e0 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65   as an undeclare
190f0 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52  d column named R
19100 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52  OWID, OID, or _R
19110 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73  OWID_ as long as
19120 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20   those.** names 
19130 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65  are not also use
19140 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20  d by explicitly 
19150 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73  declared columns
19160 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62  . ^If.** the tab
19170 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20  le has a column 
19180 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52  of type [INTEGER
19190 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68   PRIMARY KEY] th
191a0 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a  en that column.*
191b0 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69  * is another ali
191c0 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64  as for the rowid
191d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
191e0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
191f0 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66  _rowid(D) interf
19200 61 63 65 20 75 73 75 61 6c 6c 79 20 72 65 74 75  ace usually retu
19210 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  rns the [rowid] 
19220 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72  of.** the most r
19230 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c  ecent successful
19240 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61   [INSERT] into a
19250 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20   rowid table or 
19260 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
19270 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63  ** on database c
19280 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e  onnection D. ^In
19290 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48  serts into [WITH
192a0 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
192b0 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63  s are not.** rec
192c0 6f 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75  orded. ^If no su
192d0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
192e0 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61  ]s into rowid ta
192f0 62 6c 65 73 20 68 61 76 65 20 65 76 65 72 20 6f  bles have ever o
19300 63 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74  ccurred .** on t
19310 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
19320 65 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73  ection D, then s
19330 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
19340 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75  rt_rowid(D) retu
19350 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a  rns .** zero..**
19360 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73 20 62  .** As well as b
19370 65 69 6e 67 20 73 65 74 20 61 75 74 6f 6d 61 74  eing set automat
19380 69 63 61 6c 6c 79 20 61 73 20 72 6f 77 73 20 61  ically as rows a
19390 72 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  re inserted into
193a0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62   database.** tab
193b0 6c 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  les, the value r
193c0 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
193d0 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
193e0 73 65 74 20 65 78 70 6c 69 63 69 74 6c 79 20 62  set explicitly b
193f0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  y.** [sqlite3_se
19400 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  t_last_insert_ro
19410 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d  wid()].**.** Som
19420 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
19430 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
19440 6d 61 79 20 49 4e 53 45 52 54 20 72 6f 77 73 20  may INSERT rows 
19450 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65  into rowid table
19460 73 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20  s as.** part of 
19470 63 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74 72 61  committing a tra
19480 6e 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74  nsaction (e.g. t
19490 6f 20 66 6c 75 73 68 20 64 61 74 61 20 61 63 63  o flush data acc
194a0 75 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f  umulated in memo
194b0 72 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20  ry.** to disk). 
194c0 49 6e 20 74 68 69 73 20 63 61 73 65 20 73 75 62  In this case sub
194d0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
194e0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
194f0 65 74 75 72 6e 20 74 68 65 20 72 6f 77 69 64 0a  eturn the rowid.
19500 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
19510 74 68 20 74 68 65 73 65 20 69 6e 74 65 72 6e 61  th these interna
19520 6c 20 49 4e 53 45 52 54 20 6f 70 65 72 61 74 69  l INSERT operati
19530 6f 6e 73 2c 20 77 68 69 63 68 20 6c 65 61 64 73  ons, which leads
19540 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74   to .** unintuit
19550 69 76 65 20 72 65 73 75 6c 74 73 2e 20 56 69 72  ive results. Vir
19560 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
19570 6d 65 6e 74 61 74 69 6f 6e 73 20 74 68 61 74 20  mentations that 
19580 64 6f 20 77 72 69 74 65 20 74 6f 20 72 6f 77 69  do write to rowi
19590 64 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e 20 74  d.** tables in t
195a0 68 69 73 20 77 61 79 20 63 61 6e 20 61 76 6f 69  his way can avoi
195b0 64 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 62  d this problem b
195c0 79 20 72 65 73 74 6f 72 69 6e 67 20 74 68 65 20  y restoring the 
195d0 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77  original .** row
195e0 69 64 20 76 61 6c 75 65 20 75 73 69 6e 67 20 5b  id value using [
195f0 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74  sqlite3_set_last
19600 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
19610 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
19620 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f  g .** control to
19630 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a   the user..**.**
19640 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54   ^(If an [INSERT
19650 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  ] occurs within 
19660 61 20 74 72 69 67 67 65 72 20 74 68 65 6e 20 74  a trigger then t
19670 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
19680 20 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20   .** return the 
19690 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
196a0 6e 73 65 72 74 65 64 20 72 6f 77 20 61 73 20 6c  nserted row as l
196b0 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
196c0 65 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e  er is .** runnin
196d0 67 2e 20 4f 6e 63 65 20 74 68 65 20 74 72 69 67  g. Once the trig
196e0 67 65 72 20 70 72 6f 67 72 61 6d 20 65 6e 64 73  ger program ends
196f0 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
19700 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73  rned .** by this
19710 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73   routine reverts
19720 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20   to what it was 
19730 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
19740 65 72 20 77 61 73 20 66 69 72 65 64 2e 29 5e 0a  er was fired.)^.
19750 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52  **.** ^An [INSER
19760 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
19770 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
19780 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
19790 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
197a0 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
197b0 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
197c0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
197d0 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
197e0 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e  utine.  ^Thus IN
197f0 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
19800 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
19810 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
19820 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
19830 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
19840 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
19850 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
19860 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
19870 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
19880 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e  ertion fails.  ^
19890 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20  (When INSERT OR 
198a0 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
198b0 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
198c0 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
198d0 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
198e0 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
198f0 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
19900 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
19910 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
19920 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
19930 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
19940 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
19950 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
19960 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
19970 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
19980 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29  this interface.)
19990 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ^.**.** ^For the
199a0 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
199b0 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
199c0 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
199d0 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
199e0 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
199f0 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
19a00 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
19a10 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
19a20 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62  tion is accessib
19a30 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  le to SQL statem
19a40 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20  ents via the.** 
19a50 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  [last_insert_row
19a60 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  id() SQL functio
19a70 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
19a80 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
19a90 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
19aa0 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
19ab0 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
19ac0 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
19ad0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
19ae0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
19af0 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
19b00 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
19b10 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
19b20 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
19b30 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
19b40 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
19b50 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
19b60 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
19b70 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
19b80 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
19b90 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
19ba0 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
19bb0 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
19bc0 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69  [rowid]..*/.sqli
19bd0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
19be0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
19bf0 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  wid(sqlite3*);..
19c00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19c10 53 65 74 20 74 68 65 20 4c 61 73 74 20 49 6e 73  Set the Last Ins
19c20 65 72 74 20 52 6f 77 69 64 20 76 61 6c 75 65 2e  ert Rowid value.
19c30 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
19c40 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te3.**.** The sq
19c50 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69  lite3_set_last_i
19c60 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 2c 20 52  nsert_rowid(D, R
19c70 29 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20  ) method allows 
19c80 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
19c90 74 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20 76 61  to.** set the va
19ca0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
19cb0 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  calling sqlite3_
19cc0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19cd0 64 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69  d(D) to R .** wi
19ce0 74 68 6f 75 74 20 69 6e 73 65 72 74 69 6e 67 20  thout inserting 
19cf0 61 20 72 6f 77 20 69 6e 74 6f 20 74 68 65 20 64  a row into the d
19d00 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64  atabase..*/.void
19d10 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73   sqlite3_set_las
19d20 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
19d30 71 6c 69 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f  qlite3*,sqlite3_
19d40 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int64);../*.** C
19d50 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
19d60 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
19d70 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45  s Modified.** ME
19d80 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
19d90 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
19da0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
19db0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f  umber of rows mo
19dc0 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64  dified, inserted
19dd0 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62   or.** deleted b
19de0 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  y the most recen
19df0 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
19e00 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
19e10 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
19e20 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ent on the datab
19e30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
19e40 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
19e50 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a  only parameter..
19e60 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e  ** ^Executing an
19e70 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20  y other type of 
19e80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
19e90 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68  es not modify th
19ea0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
19eb0 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63  ned by this func
19ec0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  tion..**.** ^Onl
19ed0 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64  y changes made d
19ee0 69 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49  irectly by the I
19ef0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
19f00 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
19f10 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65  t are.** conside
19f20 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20  red - auxiliary 
19f30 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
19f40 79 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  y [CREATE TRIGGE
19f50 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a  R | triggers], .
19f60 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
19f70 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50  actions] or [REP
19f80 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
19f90 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20   resolution are 
19fa0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20  not counted..** 
19fb0 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61  .** Changes to a
19fc0 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69   view that are i
19fd0 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a  ntercepted by .*
19fe0 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  * [INSTEAD OF tr
19ff0 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20  igger | INSTEAD 
1a000 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65  OF triggers] are
1a010 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54   not counted. ^T
1a020 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74  he value .** ret
1a030 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1a040 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64  _changes() immed
1a050 69 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20  iately after an 
1a060 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1a070 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61  r .** DELETE sta
1a080 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20  tement run on a 
1a090 76 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a  view is always z
1a0a0 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65  ero. Only change
1a0b0 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a  s made to real .
1a0c0 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f  ** tables are co
1a0d0 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  unted..**.** Thi
1a0e0 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d  ngs are more com
1a0f0 70 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20  plicated if the 
1a100 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1a110 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  ) function is.**
1a120 20 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20   executed while 
1a130 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
1a140 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68  m is running. Th
1a150 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66  is may happen if
1a160 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20   the.** program 
1a170 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65  uses the [change
1a180 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
1a190 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74  ], or if some ot
1a1a0 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  her callback.** 
1a1b0 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  function invokes
1a1c0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1a1d0 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73  () directly. Ess
1a1e0 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a  entially:.** .**
1a1f0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
1a200 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e  ^(Before enterin
1a210 67 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  g a trigger prog
1a220 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65  ram the value re
1a230 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20  turned by.**    
1a240 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e      sqlite3_chan
1a250 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ges() function i
1a260 73 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74  s saved. After t
1a270 68 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  he trigger progr
1a280 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61  am .**        ha
1a290 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20  s finished, the 
1a2a0 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69  original value i
1a2b0 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a  s restored.)^.**
1a2c0 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69   .**   <li> ^(Wi
1a2d0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70  thin a trigger p
1a2e0 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45  rogram each INSE
1a2f0 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44  RT, UPDATE and D
1a300 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20  ELETE .**       
1a310 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20   statement sets 
1a320 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1a330 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68  ed by sqlite3_ch
1a340 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20  anges() .**     
1a350 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69     upon completi
1a360 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66  on as normal. Of
1a370 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61   course, this va
1a380 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63  lue will not inc
1a390 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20  lude .**        
1a3a0 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66  any changes perf
1a3b0 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69  ormed by sub-tri
1a3c0 67 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71  ggers, as the sq
1a3d0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
1a3e0 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65  .**        value
1a3f0 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61   will be saved a
1a400 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65  nd restored afte
1a410 72 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67  r each sub-trigg
1a420 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a  er has run.)^.**
1a430 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54   </ul>.** .** ^T
1a440 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69  his means that i
1a450 66 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20  f the changes() 
1a460 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72  SQL function (or
1a470 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65   similar) is use
1a480 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73  d.** by the firs
1a490 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
1a4a0 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
1a4b0 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72  ment within a tr
1a4c0 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65  igger, it .** re
1a4d0 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20  turns the value 
1a4e0 61 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  as set when the 
1a4f0 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e  calling statemen
1a500 74 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e  t began executin
1a510 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20  g..** ^If it is 
1a520 75 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  used by the seco
1a530 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  nd or subsequent
1a540 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20   such statement 
1a550 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
1a560 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68   .** program, th
1a570 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1a580 20 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75   reflects the nu
1a590 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64  mber of rows mod
1a5a0 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
1a5b0 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54   previous INSERT
1a5c0 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
1a5d0 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
1a5e0 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69  hin the same tri
1a5f0 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  gger..**.** See 
1a600 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
1a610 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1a620 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
1a630 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
1a640 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
1a650 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
1a660 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
1a670 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
1a680 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
1a690 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
1a6a0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
1a6b0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
1a6c0 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
1a6d0 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
1a6e0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
1a6f0 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e  eturned.** is un
1a700 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
1a710 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
1a720 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
1a730 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
1a740 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1a750 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
1a760 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
1a770 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1a780 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
1a790 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1a7a0 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
1a7b0 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74  r of rows insert
1a7c0 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a  ed, modified or.
1a7d0 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c  ** deleted by al
1a7e0 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44  l [INSERT], [UPD
1a7f0 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
1a800 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70   statements comp
1a810 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74  leted.** since t
1a820 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1a830 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65  ection was opene
1a840 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f  d, including tho
1a850 73 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a  se executed as.*
1a860 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65  * part of trigge
1a870 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65  r programs. ^Exe
1a880 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72  cuting any other
1a890 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61   type of SQL sta
1a8a0 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e  tement.** does n
1a8b0 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61  ot affect the va
1a8c0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1a8d0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1a8e0 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20  anges()..** .** 
1a8f0 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73  ^Changes made as
1a900 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67   part of [foreig
1a910 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61  n key actions] a
1a920 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  re included in t
1a930 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74  he.** count, but
1a940 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70   those made as p
1a950 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63  art of REPLACE c
1a960 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
1a970 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e  tion are.** not.
1a980 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76   ^Changes to a v
1a990 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74  iew that are int
1a9a0 65 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54  ercepted by INST
1a9b0 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20  EAD OF triggers 
1a9c0 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  .** are not coun
1a9d0 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20  ted..** .** See 
1a9e0 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
1a9f0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  3_changes()] int
1aa00 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
1aa10 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
1aa20 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
1aa30 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
1aa40 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
1aa50 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
1aa60 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
1aa70 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
1aa80 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
1aa90 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
1aaa0 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
1aab0 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
1aac0 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
1aad0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
1aae0 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
1aaf0 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
1ab00 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
1ab10 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1ab20 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
1ab30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
1ab40 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d  nterrupt A Long-
1ab50 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a  Running Query.**
1ab60 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1ab70 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
1ab80 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79  ction causes any
1ab90 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73   pending databas
1aba0 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61  e operation to a
1abb0 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75  bort and.** retu
1abc0 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65  rn at its earlie
1abd0 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20  st opportunity. 
1abe0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
1abf0 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c  typically.** cal
1ac00 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  led in response 
1ac10 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e  to a user action
1ac20 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e   such as pressin
1ac30 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72  g "Cancel".** or
1ac40 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68   Ctrl-C where th
1ac50 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c  e user wants a l
1ac60 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74  ong query operat
1ac70 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69  ion to halt.** i
1ac80 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  mmediately..**.*
1ac90 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f  * ^It is safe to
1aca0 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
1acb0 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64  ne from a thread
1acc0 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
1acd0 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68  the.** thread th
1ace0 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  at is currently 
1acf0 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61  running the data
1ad00 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  base operation. 
1ad10 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f   But it.** is no
1ad20 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  t safe to call t
1ad30 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
1ad40 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
1ad50 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a  nection] that.**
1ad60 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69   is closed or mi
1ad70 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65  ght close before
1ad80 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1ad90 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
1ada0 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f  .** ^If an SQL o
1adb0 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79  peration is very
1adc0 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64   nearly finished
1add0 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
1ade0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74  n.** sqlite3_int
1adf0 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c  errupt() is call
1ae00 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68  ed, then it migh
1ae10 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70  t not have an op
1ae20 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20  portunity.** to 
1ae30 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  be interrupted a
1ae40 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75  nd might continu
1ae50 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  e to completion.
1ae60 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f  .**.** ^An SQL o
1ae70 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73  peration that is
1ae80 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c   interrupted wil
1ae90 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
1aea0 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20  _INTERRUPT]..** 
1aeb0 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70  ^If the interrup
1aec0 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ted SQL operatio
1aed0 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20  n is an INSERT, 
1aee0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
1aef0 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73  E.** that is ins
1af00 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20  ide an explicit 
1af10 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
1af20 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61  n the entire tra
1af30 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c  nsaction.** will
1af40 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
1af50 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a  automatically..*
1af60 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1af70 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63  3_interrupt(D) c
1af80 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74  all is in effect
1af90 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65   until all curre
1afa0 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  ntly running.** 
1afb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  SQL statements o
1afc0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
1afd0 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65  ection] D comple
1afe0 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51  te.  ^Any new SQ
1aff0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1b000 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
1b010 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
1b020 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
1b030 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74  all and before t
1b040 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73  he .** running s
1b050 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65  tatements reache
1b060 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72  s zero are inter
1b070 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65  rupted as if the
1b080 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75  y had been.** ru
1b090 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74  nning prior to t
1b0a0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1b0b0 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e  rupt() call.  ^N
1b0c0 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
1b0d0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
1b0e0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
1b0f0 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
1b100 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20  t count reaches 
1b110 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20  zero are.** not 
1b120 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20  effected by the 
1b130 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1b140 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  t()..** ^A call 
1b150 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
1b160 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63  rupt(D) that occ
1b170 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61  urs when there a
1b180 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a  re no running.**
1b190 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1b1a0 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68  is a no-op and h
1b1b0 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20  as no effect on 
1b1c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1b1d0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1b1e0 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
1b1f0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1b200 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a   call returns..*
1b210 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69  /.void sqlite3_i
1b220 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33  nterrupt(sqlite3
1b230 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1b240 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
1b250 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
1b260 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a  nt Is Complete.*
1b270 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1b280 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64  nes are useful d
1b290 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69  uring command-li
1b2a0 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
1b2b0 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
1b2c0 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
1b2d0 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
1b2e0 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20  form a complete 
1b2f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
1b300 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
1b310 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
1b320 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
1b330 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
1b340 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
1b350 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f  sing.  ^These ro
1b360 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20  utines return 1 
1b370 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
1b380 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
1b390 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
1b3a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
1b3b0 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ^A statement is 
1b3c0 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20  judged to be.** 
1b3d0 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65  complete if it e
1b3e0 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63  nds with a semic
1b3f0 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69  olon token and i
1b400 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f  s not a prefix o
1b410 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d  f a.** well-form
1b420 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ed CREATE TRIGGE
1b430 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53  R statement.  ^S
1b440 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
1b450 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
1b460 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
1b470 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
1b480 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
1b490 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
1b4a0 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
1b4b0 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
1b4c0 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
1b4d0 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
1b4e0 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
1b4f0 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
1b500 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
1b510 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
1b520 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70  nator.  ^Whitesp
1b530 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65  ace.** and comme
1b540 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  nts that follow 
1b550 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f  the final semico
1b560 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  lon are ignored.
1b570 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
1b580 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20  utines return 0 
1b590 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
1b5a0 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20   is incomplete. 
1b5b0 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79   ^If a.** memory
1b5c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
1b5d0 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e  s, then SQLITE_N
1b5e0 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64  OMEM is returned
1b5f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
1b600 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70  outines do not p
1b610 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61  arse the SQL sta
1b620 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20  tements thus.** 
1b630 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20  will not detect 
1b640 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e  syntactically in
1b650 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a  correct SQL..**.
1b660 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68  ** ^(If SQLite h
1b670 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74  as not been init
1b680 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73  ialized using [s
1b690 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
1b6a0 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74  e()] prior .** t
1b6b0 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74  o invoking sqlit
1b6c0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
1b6d0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69  then sqlite3_ini
1b6e0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
1b6f0 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  oked.** automati
1b700 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
1b710 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20  _complete16().  
1b720 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69  If that initiali
1b730 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a  zation fails,.**
1b740 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
1b750 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
1b760 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1b770 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72   will be non-zer
1b780 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  o.** regardless 
1b790 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
1b7a0 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20  t the input SQL 
1b7b0 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a  is complete.)^.*
1b7c0 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
1b7d0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
1b7e0 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61  ete()] must be a
1b7f0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1b800 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67  .** UTF-8 string
1b810 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ..**.** The inpu
1b820 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
1b830 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
1b840 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
1b850 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
1b860 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
1b870 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
1b880 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
1b890 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
1b8a0 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
1b8b0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
1b8c0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
1b8d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b8e0 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
1b8f0 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
1b900 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
1b910 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
1b920 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c  busy-handler cal
1b930 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e  lback} {busy han
1b940 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  dler}.** METHOD:
1b950 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1b960 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79  The sqlite3_busy
1b970 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20  _handler(D,X,P) 
1b980 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63  routine sets a c
1b990 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1b9a0 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74   X.** that might
1b9b0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
1b9c0 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e   argument P when
1b9d0 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d  ever.** an attem
1b9e0 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  pt is made to ac
1b9f0 63 65 73 73 20 61 20 64 61 74 61 62 61 73 65 20  cess a database 
1ba00 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64  table associated
1ba10 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61   with.** [databa
1ba20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1ba30 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68   when another th
1ba40 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
1ba50 73 73 20 68 61 73 20 74 68 65 20 74 61 62 6c 65  ss has the table
1ba60 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20   locked..** The 
1ba70 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1ba80 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  dler() interface
1ba90 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   is used to impl
1baa0 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65  ement.** [sqlite
1bab0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
1bac0 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75  ] and [PRAGMA bu
1bad0 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a  sy_timeout]..**.
1bae0 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  ** ^If the busy 
1baf0 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
1bb00 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
1bb10 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  USY].** is retur
1bb20 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  ned immediately 
1bb30 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e  upon encounterin
1bb40 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66  g the lock.  ^If
1bb50 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
1bb60 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c  ck.** is not NUL
1bb70 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  L, then the call
1bb80 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e  back might be in
1bb90 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61  voked with two a
1bba0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  rguments..**.** 
1bbb0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
1bbc0 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20  ent to the busy 
1bbd0 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70  handler is a cop
1bbe0 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70  y of the void* p
1bbf0 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ointer which.** 
1bc00 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  is the third arg
1bc10 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1bc20 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e  _busy_handler().
1bc30 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72    ^The second ar
1bc40 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65  gument to.** the
1bc50 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61   busy handler ca
1bc60 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75  llback is the nu
1bc70 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68  mber of times th
1bc80 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  at the busy hand
1bc90 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20  ler has.** been 
1bca0 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73  invoked previous
1bcb0 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ly for the same 
1bcc0 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
1bcd0 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  ^If the.** busy 
1bce0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1bcf0 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
1bd00 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
1bd10 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
1bd20 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
1bd30 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
1bd40 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64  USY] is returned
1bd50 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69  .** to the appli
1bd60 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74  cation..** ^If t
1bd70 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1bd80 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
1bd90 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d  en another attem
1bda0 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f  pt.** is made to
1bdb0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
1bdc0 62 61 73 65 20 61 6e 64 20 74 68 65 20 63 79 63  base and the cyc
1bdd0 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
1bde0 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
1bdf0 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
1be00 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
1be10 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c  tee that it will
1be20 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77   be invoked.** w
1be30 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
1be40 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49  k contention. ^I
1be50 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69  f SQLite determi
1be60 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e  nes that invokin
1be70 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61  g the busy.** ha
1be80 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75  ndler could resu
1be90 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b  lt in a deadlock
1bea0 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65  , it will go ahe
1beb0 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  ad and return [S
1bec0 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74  QLITE_BUSY].** t
1bed0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
1bee0 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  n instead of inv
1bef0 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75  oking the .** bu
1bf00 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43  sy handler..** C
1bf10 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72  onsider a scenar
1bf20 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f  io where one pro
1bf30 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
1bf40 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74  a read lock that
1bf50 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67  .** it is trying
1bf60 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
1bf70 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61   reserved lock a
1bf80 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70  nd.** a second p
1bf90 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
1bfa0 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  g a reserved loc
1bfb0 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79  k that it is try
1bfc0 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  ing.** to promot
1bfd0 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76  e to an exclusiv
1bfe0 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72  e lock.  The fir
1bff0 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  st process canno
1c000 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63  t proceed.** bec
1c010 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
1c020 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
1c030 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
1c040 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a  process cannot.*
1c050 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73  * proceed becaus
1c060 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1c070 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49  by the first.  I
1c080 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73  f both processes
1c090 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62  .** invoke the b
1c0a0 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65  usy handlers, ne
1c0b0 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20  ither will make 
1c0c0 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54  any progress.  T
1c0d0 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c  herefore,.** SQL
1c0e0 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ite returns [SQL
1c0f0 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68  ITE_BUSY] for th
1c100 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c  e first process,
1c110 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69   hoping that thi
1c120 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65  s.** will induce
1c130 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
1c140 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74  ss to release it
1c150 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20  s read lock and 
1c160 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63  allow.** the sec
1c170 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70  ond process to p
1c180 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  roceed..**.** ^T
1c190 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
1c1a0 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
1c1b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
1c1c0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
1c1d0 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
1c1e0 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
1c1f0 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
1c200 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
1c210 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
1c220 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
1c230 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
1c240 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e  y set handler.)^
1c250 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c    ^Note that cal
1c260 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
1c270 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
1c280 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b   or evaluating [
1c290 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
1c2a0 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e  out=N] will chan
1c2b0 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68  ge the.** busy h
1c2c0 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20  andler and thus 
1c2d0 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f  clear any previo
1c2e0 75 73 6c 79 20 73 65 74 20 62 75 73 79 20 68 61  usly set busy ha
1c2f0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
1c300 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
1c310 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
1c320 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
1c330 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
1c340 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c350 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1c360 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1c370 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
1c380 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  s,.** the busy h
1c390 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65  andler is not re
1c3a0 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75  entrant.  Any su
1c3b0 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65  ch actions.** re
1c3c0 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
1c3d0 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a  d behavior..** .
1c3e0 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  ** A busy handle
1c3f0 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
1c400 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1c410 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b  nnection.** or [
1c420 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1c430 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
1c440 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1c450 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
1c460 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
1c470 71 6c 69 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76  qlite3*,int(*)(v
1c480 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29  oid*,int),void*)
1c490 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c4a0 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
1c4b0 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  meout.** METHOD:
1c4c0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1c4d0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
1c4e0 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
1c4f0 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
1c500 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
1c510 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
1c520 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
1c530 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
1c540 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
1c550 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a   ^The handler.**
1c560 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
1c570 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
1c580 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1c590 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1c5a0 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20  leeping.** have 
1c5b0 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41  accumulated.  ^A
1c5c0 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d  fter at least "m
1c5d0 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
1c5e0 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
1c5f0 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
1c600 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
1c610 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
1c620 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
1c630 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
1c640 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74  **.** ^Calling t
1c650 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
1c660 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
1c670 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
1c680 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
1c690 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
1c6a0 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ndlers..**.** ^(
1c6b0 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
1c6c0 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
1c6d0 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
1c6e0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
1c6f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c700 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d  ] at any given m
1c710 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68  oment.  If anoth
1c720 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a  er busy handler.
1c730 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20  ** was defined  
1c740 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  (using [sqlite3_
1c750 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29  busy_handler()])
1c760 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
1c770 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  g.** this routin
1c780 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75  e, that other bu
1c790 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c  sy handler is cl
1c7a0 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  eared.)^.**.** S
1c7b0 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d  ee also:  [PRAGM
1c7c0 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a  A busy_timeout].
1c7d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1c7e0 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
1c7f0 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
1c800 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c810 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
1c820 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
1c830 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48   Queries.** METH
1c840 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1c850 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61  * This is a lega
1c860 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  cy interface tha
1c870 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66  t is preserved f
1c880 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
1c890 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55  patibility..** U
1c8a0 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  se of this inter
1c8b0 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f  face is not reco
1c8c0 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44  mmended..**.** D
1c8d0 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
1c8e0 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
1c8f0 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
1c900 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
1c910 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
1c920 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1c930 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
1c940 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
1c950 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
1c960 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
1c970 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
1c980 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
1c990 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
1c9a0 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
1c9b0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
1c9c0 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
1c9d0 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
1c9e0 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
1c9f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1ca00 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
1ca10 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
1ca20 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
1ca30 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
1ca40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
1ca50 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
1ca60 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
1ca70 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
1ca80 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
1ca90 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
1caa0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
1cab0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
1cac0 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
1cad0 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
1cae0 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
1caf0 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
1cb00 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
1cb10 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
1cb20 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
1cb30 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
1cb40 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
1cb50 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
1cb60 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
1cb70 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
1cb80 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
1cb90 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
1cba0 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
1cbb0 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
1cbc0 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
1cbd0 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
1cbe0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
1cbf0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
1cc00 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
1cc10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
1cc20 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
1cc30 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
1cc40 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
1cc50 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
1cc60 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
1cc70 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
1cc80 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
1cc90 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
1cca0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1ccb0 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
1ccc0 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
1ccd0 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
1cce0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
1ccf0 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
1cd00 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  ^(As an example 
1cd10 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
1cd20 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70  ble format, supp
1cd30 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75  ose a query resu
1cd40 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c  lt.** is as foll
1cd50 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1cd60 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1cd70 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
1cd80 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
1cd90 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
1cda0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
1cdb0 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
1cdc0 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
1cdd0 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
1cde0 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
1cdf0 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
1ce00 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1ce10 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61  e>.**.** There a
1ce20 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d  re two column (M
1ce30 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72  ==2) and three r
1ce40 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75  ows (N==3).  Thu
1ce50 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  s the.** result 
1ce60 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72  table has 8 entr
1ce70 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68  ies.  Suppose th
1ce80 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
1ce90 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
1cea0 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a  n array names az
1ceb0 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a  Result.  Then az
1cec0 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69  Result holds thi
1ced0 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a  s content:.**.**
1cee0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1cef0 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
1cf00 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
1cf10 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
1cf20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
1cf30 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
1cf40 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1cf50 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
1cf60 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1cf70 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
1cf80 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1cf90 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
1cfa0 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
1cfb0 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
1cfc0 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
1cfd0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
1cfe0 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
1cff0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1d000 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
1d010 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1d020 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
1d030 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1d040 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76  le() function ev
1d050 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d  aluates one or m
1d060 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ore.** semicolon
1d070 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73  -separated SQL s
1d080 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
1d090 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1d0a0 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67   UTF-8.** string
1d0b0 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61   of its 2nd para
1d0c0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
1d0d0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
1d0e0 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74   to the.** point
1d0f0 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20  er given in its 
1d100 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  3rd parameter..*
1d110 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61  *.** After the a
1d120 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66  pplication has f
1d130 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65  inished with the
1d140 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c   result from sql
1d150 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1d160 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73  ,.** it must pas
1d170 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  s the result tab
1d180 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  le pointer to sq
1d190 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1d1a0 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
1d1b0 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
1d1c0 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
1d1d0 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
1d1e0 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
1d1f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
1d200 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
1d210 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
1d220 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
1d230 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
1d240 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
1d250 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
1d260 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
1d270 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
1d280 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1d290 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
1d2a0 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
1d2b0 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
1d2c0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
1d2d0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1d2e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
1d2f0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
1d300 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
1d310 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
1d320 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
1d330 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
1d340 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
1d350 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
1d360 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
1d370 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
1d380 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
1d390 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
1d3a0 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
1d3b0 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
1d3c0 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
1d3d0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
1d3e0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
1d3f0 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
1d400 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
1d410 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
1d420 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
1d430 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
1d440 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1d450 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
1d460 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  code()] or.** [s
1d470 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1d480 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1d490 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
1d4a0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1d4b0 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
1d4c0 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
1d4d0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
1d4e0 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
1d4f0 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
1d500 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
1d510 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
1d520 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
1d530 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
1d540 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1d550 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
1d560 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1d570 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
1d580 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
1d590 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
1d5a0 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
1d5b0 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
1d5c0 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
1d5d0 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
1d5e0 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69  n here */.);.voi
1d5f0 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
1d600 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
1d610 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
1d620 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
1d630 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
1d640 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1d650 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1d660 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f  re work-alikes o
1d670 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
1d680 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
1d690 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
1d6a0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1d6b0 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ary..** These ro
1d6c0 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e  utines understan
1d6d0 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f  d most of the co
1d6e0 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74  mmon K&R formatt
1d6f0 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20  ing options,.** 
1d700 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69  plus some additi
1d710 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72  onal non-standar
1d720 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69  d formats, detai
1d730 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f  led below..** No
1d740 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20  te that some of 
1d750 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65  the more obscure
1d760 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1d770 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a  ons from recent.
1d780 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61  ** C-library sta
1d790 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74  ndards are omitt
1d7a0 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70  ed from this imp
1d7b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a  lementation..**.
1d7c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1d7d0 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
1d7e0 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
1d7f0 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
1d800 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
1d810 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
1d820 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
1d830 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
1d840 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
1d850 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
1d860 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
1d870 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
1d880 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
1d890 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72  ree()].  ^Both r
1d8a0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
1d8b0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
1d8c0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
1d8d0 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
1d8e0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
1d8f0 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
1d900 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
1d910 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
1d920 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
1d930 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
1d940 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
1d950 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
1d960 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
1d970 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
1d980 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
1d990 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
1d9a0 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
1d9b0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1d9c0 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
1d9d0 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
1d9e0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
1d9f0 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
1da00 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
1da10 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
1da20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
1da30 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
1da40 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
1da50 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
1da60 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
1da70 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
1da80 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
1da90 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
1daa0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
1dab0 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
1dac0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1dad0 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
1dae0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
1daf0 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
1db00 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
1db10 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
1db20 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
1db30 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
1db40 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
1db50 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
1db60 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
1db70 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
1db80 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
1db90 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
1dba0 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
1dbb0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
1dbc0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1dbd0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
1dbe0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1dbf0 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
1dc00 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
1dc10 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
1dc20 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
1dc30 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
1dc40 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
1dc50 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
1dc60 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
1dc70 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
1dc80 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
1dc90 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
1dca0 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
1dcb0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
1dcc0 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
1dcd0 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
1dce0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
1dcf0 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
1dd00 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
1dd10 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
1dd20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
1dd30 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
1dd40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1dd50 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72  e3_vsnprintf() r
1dd60 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61  outine is a vara
1dd70 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  rgs version of s
1dd80 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1dd90 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )..**.** These r
1dda0 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
1ddb0 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
1ddc0 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
1ddd0 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
1dde0 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
1ddf0 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
1de00 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
1de10 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
1de20 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
1de30 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
1de40 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
1de50 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
1de60 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25  e "%q", "%Q", "%
1de70 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69  w" and "%z" opti
1de80 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ons..**.** ^(The
1de90 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
1dea0 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
1deb0 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
1dec0 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
1ded0 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
1dee0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
1def0 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
1df00 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
1df10 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
1df20 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
1df30 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
1df40 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1df50 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  )^  By doubling 
1df60 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
1df70 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
1df80 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
1df90 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
1dfa0 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
1dfb0 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
1dfc0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
1dfd0 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
1dfe0 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
1dff0 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
1e000 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
1e010 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1e020 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1e030 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
1e040 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
1e050 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1e060 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
1e070 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
1e080 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
1e090 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
1e0a0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1e0b0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1e0c0 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1e0d0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1e0e0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1e0f0 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
1e100 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
1e110 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
1e120 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
1e130 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
1e140 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1e150 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
1e160 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
1e170 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
1e180 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
1e190 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
1e1a0 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
1e1b0 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
1e1c0 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
1e1d0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1e1e0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1e1f0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1e200 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
1e210 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
1e220 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1e230 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1e240 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
1e250 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
1e260 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
1e270 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
1e280 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
1e290 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
1e2a0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1e2b0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1e2c0 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1e2d0 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
1e2e0 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
1e2f0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1e300 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
1e310 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
1e320 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
1e330 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
1e340 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
1e350 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
1e360 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
1e370 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
1e380 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
1e390 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
1e3a0 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f  * ^(The %Q optio
1e3b0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
1e3c0 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
1e3d0 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
1e3e0 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
1e3f0 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
1e400 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
1e410 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
1e420 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
1e430 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
1e440 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
1e450 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
1e460 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
1e470 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
1e480 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
1e490 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ).)^  So, for ex
1e4a0 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
1e4b0 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
1e4c0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1e4d0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1e4e0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1e4f0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1e500 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
1e510 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1e520 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1e530 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1e540 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1e550 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1e560 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1e570 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
1e580 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
1e590 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
1e5a0 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
1e5b0 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
1e5c0 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
1e5d0 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
1e5e0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1e5f0 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61  ^(The "%w" forma
1e600 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20  tting option is 
1e610 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65 70 74  like "%q" except
1e620 20 74 68 61 74 20 69 74 20 65 78 70 65 63 74 73   that it expects
1e630 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69   to.** be contai
1e640 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c  ned within doubl
1e650 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64  e-quotes instead
1e660 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65   of single quote
1e670 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63  s, and it.** esc
1e680 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d  apes the double-
1e690 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 72 20  quote character 
1e6a0 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 73  instead of the s
1e6b0 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63  ingle-quote.** c
1e6c0 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65  haracter.)^  The
1e6d0 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%w" formatting
1e6e0 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e   option is inten
1e6f0 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69  ded for safely i
1e700 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c  nserting.** tabl
1e710 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  e and column nam
1e720 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72  es into a constr
1e730 75 63 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  ucted SQL statem
1e740 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ent..**.** ^(The
1e750 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
1e760 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1e770 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68  ke "%s" but with
1e780 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
1e790 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
1e7a0 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
1e7b0 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
1e7c0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
1e7d0 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
1e7e0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
1e7f0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
1e800 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73  ng.)^.*/.char *s
1e810 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
1e820 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
1e830 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
1e840 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1e850 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
1e860 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
1e870 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
1e880 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
1e890 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1e8a0 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  _vsnprintf(int,c
1e8b0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1e8c0 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a  , va_list);../*.
1e8d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1e8e0 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
1e8f0 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
1e900 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
1e910 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
1e920 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
1e930 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
1e940 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
1e950 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
1e960 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
1e970 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
1e980 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
1e990 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
1e9a0 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
1e9b0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
1e9c0 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
1e9d0 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
1e9e0 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
1e9f0 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
1ea00 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
1ea10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1ea20 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
1ea30 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1ea40 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
1ea50 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
1ea60 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
1ea70 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
1ea80 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
1ea90 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
1eaa0 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
1eab0 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
1eac0 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
1ead0 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
1eae0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1eaf0 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
1eb00 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
1eb10 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
1eb20 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
1eb30 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
1eb40 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
1eb50 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
1eb60 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
1eb70 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e  lite3_malloc64(N
1eb80 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20  ) routine works 
1eb90 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c  just like.** sql
1eba0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65  ite3_malloc(N) e
1ebb0 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20  xcept that N is 
1ebc0 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62  an unsigned 64-b
1ebd0 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65  it integer inste
1ebe0 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65  ad.** of a signe
1ebf0 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72  d 32-bit integer
1ec00 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1ec10 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1ec20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
1ec30 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
1ec40 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
1ec50 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1ec60 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1ec70 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
1ec80 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
1ec90 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
1eca0 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
1ecb0 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
1ecc0 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
1ecd0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1ece0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1ecf0 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
1ed00 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
1ed10 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1ed20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
1ed30 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
1ed40 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
1ed50 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
1ed60 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
1ed70 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
1ed80 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
1ed90 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
1eda0 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
1edb0 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
1edc0 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
1edd0 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
1ede0 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
1edf0 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
1ee00 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1ee10 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
1ee20 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
1ee30 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
1ee40 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
1ee50 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
1ee60 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
1ee70 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
1ee80 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1ee90 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
1eea0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
1eeb0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65  ealloc(X,N) inte
1eec0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
1eed0 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
1eee0 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
1eef0 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74  ation X to be at
1ef00 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a   least N bytes..
1ef10 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61 72  ** ^If the X par
1ef20 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1ef30 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a  3_realloc(X,N).*
1ef40 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
1ef50 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68  ter then its beh
1ef60 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63  avior is identic
1ef70 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  al to calling.**
1ef80 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1ef90 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  N)..** ^If the N
1efa0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1efb0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1efc0 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a  N) is zero or.**
1efd0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74   negative then t
1efe0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65  he behavior is e
1eff0 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
1f000 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  as calling.** sq
1f010 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a  lite3_free(X)..*
1f020 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  * ^sqlite3_reall
1f030 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20  oc(X,N) returns 
1f040 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  a pointer to a m
1f050 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1f060 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
1f070 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
1f080 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66  or NULL if insuf
1f090 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
1f0a0 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
1f0b0 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a  ^If M is the siz
1f0c0 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
1f0d0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
1f0e0 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
1f0f0 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
1f100 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
1f110 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
1f120 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
1f130 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
1f140 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f150 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72  (X,N) and the pr
1f160 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
1f170 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
1f180 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f190 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  X,N) returns NUL
1f1a0 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74  L and N is posit
1f1b0 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ive, then the.**
1f1c0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1f1d0 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a  n is not freed..
1f1e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1f1f0 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e  e3_realloc64(X,N
1f200 29 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72  ) interfaces wor
1f210 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a  ks the same as.*
1f220 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  * sqlite3_reallo
1f230 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68  c(X,N) except th
1f240 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74  at N is a 64-bit
1f250 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
1f260 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  r instead.** of 
1f270 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  a 32-bit signed 
1f280 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  integer..**.** ^
1f290 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79  If X is a memory
1f2a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76   allocation prev
1f2b0 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
1f2c0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
1f2d0 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
1f2e0 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71  3_malloc64(), sq
1f2f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
1f300 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1f310 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a  loc64(), then.**
1f320 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1f330 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69  ) returns the si
1f340 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72  ze of that memor
1f350 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20  y allocation in 
1f360 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76  bytes..** ^The v
1f370 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1f380 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1f390 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65  ) might be large
1f3a0 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65  r than the numbe
1f3b0 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65  r.** of bytes re
1f3c0 71 75 65 73 74 65 64 20 77 68 65 6e 20 58 20 77  quested when X w
1f3d0 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e  as allocated.  ^
1f3e0 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70  If X is a NULL p
1f3f0 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73  ointer then.** s
1f400 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1f410 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49  returns zero.  I
1f420 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f  f X points to so
1f430 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69 73 20  mething that is 
1f440 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e  not.** the begin
1f450 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ning of memory a
1f460 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66  llocation, or if
1f470 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20   it points to a 
1f480 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69  formerly.** vali
1f490 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
1f4a0 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77  ion that has now
1f4b0 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65   been freed, the
1f4c0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  n the behavior.*
1f4d0 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69  * of sqlite3_msi
1f4e0 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e  ze(X) is undefin
1f4f0 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20  ed and possibly 
1f500 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
1f510 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
1f520 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
1f530 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33  alloc(), sqlite3
1f540 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  _realloc(),.** s
1f550 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1f560 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
1f570 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73  ealloc64().** is
1f580 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20   always aligned 
1f590 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38  to at least an 8
1f5a0 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20   byte boundary, 
1f5b0 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74  or to a.** 4 byt
1f5c0 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68  e boundary if th
1f5d0 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45  e [SQLITE_4_BYTE
1f5e0 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d  _ALIGNED_MALLOC]
1f5f0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
1f600 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
1f610 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65  .**.** In SQLite
1f620 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61   version 3.5.0 a
1f630 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73  nd 3.5.1, it was
1f640 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66   possible to def
1f650 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54  ine.** the SQLIT
1f660 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
1f670 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77  LOCATION which w
1f680 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62  ould cause the b
1f690 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65  uilt-in.** imple
1f6a0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
1f6b0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  se routines to b
1f6c0 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74  e omitted.  That
1f6d0 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
1f6e0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76  s no longer prov
1f6f0 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c  ided.  Only buil
1f700 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
1f710 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73  cators can be us
1f720 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20  ed..**.** Prior 
1f730 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  to SQLite versio
1f740 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69  n 3.7.10, the Wi
1f750 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61  ndows OS interfa
1f760 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a  ce layer called.
1f770 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
1f780 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
1f790 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
1f7a0 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
1f7b0 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
1f7c0 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
1f7d0 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
1f7e0 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
1f7f0 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
1f800 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
1f810 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69  he particular Wi
1f820 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
1f830 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
1f840 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
1f850 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20   were detected, 
1f860 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65  but.** they were
1f870 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
1f880 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
1f890 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
1f8a0 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
1f8b0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
1f8c0 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  EM]..**.** The p
1f8d0 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
1f8e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1f8f0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1f900 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
1f910 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
1f920 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e  ULL or else poin
1f930 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ters obtained fr
1f940 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e  om a prior.** in
1f950 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
1f960 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
1f970 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1f980 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
1f990 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20  ** not yet been 
1f9a0 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
1f9b0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
1f9c0 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
1f9d0 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
1f9e0 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66  of.** a block of
1f9f0 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
1fa00 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
1fa10 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
1fa20 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20  ite3_free()] or 
1fa30 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1fa40 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ()]..*/.void *sq
1fa50 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
1fa60 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
1fa70 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65  _malloc64(sqlite
1fa80 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  3_uint64);.void 
1fa90 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
1faa0 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
1fab0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
1fac0 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c  loc64(void*, sql
1fad0 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f  ite3_uint64);.vo
1fae0 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
1faf0 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  void*);.sqlite3_
1fb00 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  uint64 sqlite3_m
1fb10 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  size(void*);../*
1fb20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
1fb30 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
1fb40 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  tatistics.**.** 
1fb50 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
1fb60 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
1fb70 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
1fb80 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
1fb90 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
1fba0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
1fbb0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
1fbc0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1fbd0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
1fbe0 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
1fbf0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
1fc00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1fc10 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
1fc20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1fc30 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
1fc40 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1fc50 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1fc60 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63  s.** of memory c
1fc70 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
1fc80 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
1fc90 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
1fca0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1fcb0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1fcc0 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
1fcd0 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
1fce0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  ** value of [sql
1fcf0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1fd00 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
1fd10 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1fd20 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
1fd30 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65    ^The values re
1fd40 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1fd50 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1fd60 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1fd70 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1fd80 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
1fd90 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64  y overhead.** ad
1fda0 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e  ded by SQLite in
1fdb0 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   its implementat
1fdc0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1fdd0 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75  malloc()],.** bu
1fde0 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
1fdf0 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
1fe00 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
1fe10 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75  m library.** rou
1fe20 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
1fe30 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
1fe40 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y call..**.** ^T
1fe50 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
1fe60 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
1fe70 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
1fe80 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73  t value of.** [s
1fe90 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1fea0 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
1feb0 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
1fec0 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
1fed0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1fee0 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
1fef0 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
1ff00 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
1ff10 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1ff20 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
1ff30 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1ff40 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72  * prior to the r
1ff50 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  eset..*/.sqlite3
1ff60 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
1ff70 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
1ff80 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
1ff90 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1ffa0 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73  ighwater(int res
1ffb0 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  etFlag);../*.** 
1ffc0 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f  CAPI3REF: Pseudo
1ffd0 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47  -Random Number G
1ffe0 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53  enerator.**.** S
1fff0 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61  QLite contains a
20000 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73   high-quality ps
20010 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62  eudo-random numb
20020 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52  er generator (PR
20030 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73  NG) used to.** s
20040 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f  elect random [RO
20050 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68  WID | ROWIDs] wh
20060 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77  en inserting new
20070 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20   records into a 
20080 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c  table that.** al
20090 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c  ready uses the l
200a0 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20  argest possible 
200b0 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52  [ROWID].  The PR
200c0 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
200d0 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
200e0 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
200f0 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
20100 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
20110 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
20120 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ows.** applicati
20130 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  ons to access th
20140 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20  e same PRNG for 
20150 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a  other purposes..
20160 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  **.** ^A call to
20170 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   this routine st
20180 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20  ores N bytes of 
20190 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
201a0 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68  buffer P..** ^Th
201b0 65 20 50 20 70 61 72 61 6d 65 74 65 72 20 63 61  e P parameter ca
201c0 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n be a NULL poin
201d0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ter..**.** ^If t
201e0 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20  his routine has 
201f0 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75  not been previou
20200 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66  sly called or if
20210 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a   the previous.**
20220 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73   call had N less
20230 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e   than one or a N
20240 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
20250 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47  P, then the PRNG
20260 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73   is.** seeded us
20270 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
20280 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65  btained from the
20290 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
202a0 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65  hod of.** the de
202b0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
202c0 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  fs] object..** ^
202d0 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  If the previous 
202e0 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
202f0 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66  tine had an N of
20300 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61   1 or more and a
20310 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74  .** non-NULL P t
20320 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72  hen the pseudo-r
20330 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e  andomness is gen
20340 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e  erated.** intern
20350 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74  ally and without
20360 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65   recourse to the
20370 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
20380 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65  Randomness.** me
20390 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  thod..*/.void sq
203a0 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
203b0 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29  (int N, void *P)
203c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
203d0 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
203e0 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
203f0 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f  llbacks.** METHO
20400 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45  D: sqlite3.** KE
20410 59 57 4f 52 44 53 3a 20 7b 61 75 74 68 6f 72 69  YWORDS: {authori
20420 7a 65 72 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a  zer callback}.**
20430 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
20440 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61  e registers an a
20450 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20460 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ck with a partic
20470 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
20480 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73  e connection], s
20490 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66  upplied in the f
204a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
204b0 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65  * ^The authorize
204c0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
204d0 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
204e0 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e  tements are bein
204f0 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79  g compiled.** by
20500 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20510 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
20520 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  ants [sqlite3_pr
20530 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20  epare_v2()],.** 
20540 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20550 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v3()], [sqlite3
20560 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 5b  _prepare16()], [
20570 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20580 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20  6_v2()],.** and 
20590 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
205a0 31 36 5f 76 33 28 29 5d 2e 20 20 5e 41 74 20 76  16_v3()].  ^At v
205b0 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
205c0 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
205d0 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
205e0 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
205f0 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
20600 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
20610 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
20620 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20630 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
20640 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
20650 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
20660 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f  wed.  ^The autho
20670 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73  rizer callback s
20680 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
20690 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61  [SQLITE_OK] to a
206a0 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
206b0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
206c0 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
206d0 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
206e0 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
206f0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
20700 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
20710 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
20720 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
20730 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
20740 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
20750 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
20760 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
20770 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68  r.  ^If the auth
20780 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
20790 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76  returns.** any v
207a0 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
207b0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
207c0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
207d0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a   [SQLITE_DENY].*
207e0 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  * then the [sqli
207f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
20800 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
20810 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
20820 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
20830 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
20840 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
20850 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ssage..**.** Whe
20860 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
20870 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
20880 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
20890 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
208a0 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
208b0 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c    ^When the call
208c0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
208d0 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
208e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
208f0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
20900 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
20910 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
20920 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
20930 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
20940 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
20950 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
20960 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
20970 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  d. .**.** ^The f
20980 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
20990 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
209a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
209b0 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
209c0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
209d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
209e0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
209f0 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65  terface. ^The se
20a00 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
20a10 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
20a20 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
20a30 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
20a40 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
20a50 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
20a60 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
20a70 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
20a80 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64  ized. ^The third
20a90 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
20aa0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
20ab0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
20ac0 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69   either NULL poi
20ad0 6e 74 65 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65  nters or zero-te
20ae0 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
20af0 0a 2a 2a 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  .** that contain
20b00 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61   additional deta
20b10 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
20b20 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
20b30 72 69 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63  rized..** Applic
20b40 61 74 69 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61  ations must alwa
20b50 79 73 20 62 65 20 70 72 65 70 61 72 65 64 20 74  ys be prepared t
20b60 6f 20 65 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55  o encounter a NU
20b70 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e  LL pointer in an
20b80 79 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 69 72  y.** of the thir
20b90 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 73 69  d through the si
20ba0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 6f  xth parameters o
20bb0 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  f the authorizat
20bc0 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ion callback..**
20bd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
20be0 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
20bf0 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20  TE_READ].** and 
20c00 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
20c10 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e  urns [SQLITE_IGN
20c20 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ORE] then the.**
20c30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
20c40 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20  ment] statement 
20c50 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
20c60 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20  o substitute.** 
20c70 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
20c80 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
20c90 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
20ca0 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65  ould have.** bee
20cb0 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
20cc0 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
20cd0 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53  eturned.  The [S
20ce0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a  QLITE_IGNORE].**
20cf0 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75   return can be u
20d00 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75  sed to deny an u
20d10 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63  ntrusted user ac
20d20 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75  cess to individu
20d30 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66  al.** columns of
20d40 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68   a table..** ^Wh
20d50 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 72 65  en a table is re
20d60 66 65 72 65 6e 63 65 64 20 62 79 20 61 20 5b 53  ferenced by a [S
20d70 45 4c 45 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f  ELECT] but no co
20d80 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61 72 65 0a  lumn values are.
20d90 2a 2a 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  ** extracted fro
20da0 6d 20 74 68 61 74 20 74 61 62 6c 65 20 28 66 6f  m that table (fo
20db0 72 20 65 78 61 6d 70 6c 65 20 69 6e 20 61 20 71  r example in a q
20dc0 75 65 72 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45  uery like.** "SE
20dd0 4c 45 43 54 20 63 6f 75 6e 74 28 2a 29 20 46 52  LECT count(*) FR
20de0 4f 4d 20 74 61 62 22 29 20 74 68 65 6e 20 74 68  OM tab") then th
20df0 65 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20  e [SQLITE_READ] 
20e00 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20e10 61 63 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ack.** is invoke
20e20 64 20 6f 6e 63 65 20 66 6f 72 20 74 68 61 74 20  d once for that 
20e30 74 61 62 6c 65 20 77 69 74 68 20 61 20 63 6f 6c  table with a col
20e40 75 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20 69 73  umn name that is
20e50 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
20e60 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
20e70 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
20e80 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
20e90 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
20ea0 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
20eb0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
20ec0 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
20ed0 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
20ee0 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
20ef0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
20f00 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
20f10 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
20f20 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
20f30 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
20f40 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
20f50 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
20f60 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
20f70 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
20f80 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
20f90 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
20fa0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
20fb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
20fc0 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
20fd0 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
20fe0 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
20ff0 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
21000 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
21010 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
21020 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
21030 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
21040 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
21050 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
21060 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
21070 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
21080 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
21090 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
210a0 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
210b0 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
210c0 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
210d0 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
210e0 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
210f0 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
21100 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
21110 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
21120 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
21130 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
21140 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
21150 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
21160 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
21170 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
21180 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
21190 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
211a0 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
211b0 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
211c0 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
211d0 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
211e0 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
211f0 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
21200 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
21210 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
21220 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
21230 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
21240 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
21250 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
21260 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
21270 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
21280 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
21290 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
212a0 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
212b0 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
212c0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
212d0 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
212e0 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
212f0 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
21300 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
21310 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
21320 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
21330 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
21340 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
21350 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
21360 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
21370 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
21380 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
21390 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
213a0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
213b0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
213c0 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
213d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
213e0 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
213f0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
21400 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
21410 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21420 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
21430 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
21440 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
21450 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
21460 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
21470 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
21480 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
21490 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
214a0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
214b0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
214c0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
214d0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
214e0 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
214f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
21500 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
21510 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
21520 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
21530 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
21540 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
21550 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
21560 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
21570 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
21580 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
21590 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
215a0 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
215b0 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
215c0 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
215d0 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
215e0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
215f0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
21600 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
21610 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
21620 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
21630 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
21640 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
21650 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
21660 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
21670 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
21680 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
21690 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
216a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
216b0 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
216c0 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
216d0 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
216e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
216f0 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
21700 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
21710 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
21720 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
21730 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
21740 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74  .int sqlite3_set
21750 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
21760 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
21770 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
21780 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
21790 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
217a0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
217b0 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
217c0 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
217d0 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
217e0 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
217f0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
21800 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
21810 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
21820 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
21830 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
21840 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
21850 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
21860 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
21870 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
21880 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
21890 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
218a0 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
218b0 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
218c0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
218d0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
218e0 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
218f0 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
21900 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
21910 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
21920 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
21930 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
21940 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63  ed as a [conflic
21950 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64  t resolution mod
21960 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66  e].** returned f
21970 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
21980 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
21990 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  t()] interface..
219a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
219b0 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
219c0 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
219d0 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
219e0 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
219f0 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
21a00 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
21a10 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
21a20 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
21a30 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
21a40 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
21a50 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
21a60 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
21a70 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
21a80 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
21a90 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
21aa0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
21ab0 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
21ac0 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
21ad0 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
21ae0 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
21af0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
21b00 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
21b10 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
21b20 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
21b30 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
21b40 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
21b50 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
21b60 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
21b70 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
21b80 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
21b90 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21ba0 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
21bb0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
21bc0 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
21bd0 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
21be0 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
21bf0 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
21c00 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
21c10 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
21c20 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
21c30 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
21c40 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
21c50 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
21c60 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
21c70 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
21c80 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
21c90 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
21ca0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28  d parameter.  ^(
21cb0 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
21cc0 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
21cd0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
21ce0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
21cf0 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
21d00 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
21d10 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
21d20 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68  ble.)^  ^The 6th
21d30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
21d40 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
21d50 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
21d60 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
21d70 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
21d80 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
21d90 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
21da0 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
21db0 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
21dc0 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
21dd0 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
21de0 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
21df0 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
21e00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21e10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21e20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
21e30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
21e40 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
21e50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
21e60 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
21e70 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
21e80 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
21e90 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
21ea0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
21eb0 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
21ec0 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
21ed0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
21ee0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
21ef0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
21f00 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
21f10 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
21f20 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
21f30 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
21f40 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
21f50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
21f60 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
21f70 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
21f80 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21f90 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
21fa0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
21fb0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
21fc0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
21fd0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21fe0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
21ff0 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
22000 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
22010 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22020 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22030 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
22040 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
22050 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
22060 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
22070 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22080 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
22090 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
220a0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
220b0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
220c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
220d0 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
220e0 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
220f0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
22100 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22110 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22120 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
22130 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
22140 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
22150 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22160 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22170 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
22180 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
22190 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
221a0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
221b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
221c0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
221d0 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
221e0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
221f0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
22200 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22210 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
22220 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
22230 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
22240 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22250 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22260 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
22270 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
22280 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
22290 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
222a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
222b0 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
222c0 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
222d0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
222e0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
222f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22300 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
22310 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
22320 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
22330 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
22340 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22350 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
22360 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
22370 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
22380 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22390 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
223a0 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
223b0 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
223c0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
223d0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
223e0 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
223f0 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
22400 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
22410 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
22420 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
22430 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
22440 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
22450 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
22460 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
22470 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
22480 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
22490 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
224a0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
224b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
224c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
224d0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
224e0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
224f0 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
22500 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22510 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22520 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
22530 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
22540 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22550 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
22560 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22570 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
22580 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
22590 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
225a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
225b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
225c0 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
225d0 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
225e0 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
225f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22600 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22610 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
22620 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
22630 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
22640 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22650 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22660 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
22670 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
22680 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
22690 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
226a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
226b0 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
226c0 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
226d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
226e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
226f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22700 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
22710 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
22720 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
22730 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
22740 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22750 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
22760 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
22770 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
22780 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
22790 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
227a0 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
227b0 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
227c0 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
227d0 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
227e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
227f0 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
22800 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
22810 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
22820 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
22830 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
22840 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
22850 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
22860 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66  ger used */.#def
22870 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52  ine SQLITE_RECUR
22880 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20  SIVE            
22890 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  33   /* NULL    
228a0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
228b0 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a          */../*.*
228c0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
228d0 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
228e0 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d  g Functions.** M
228f0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
22900 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
22910 6e 65 73 20 61 72 65 20 64 65 70 72 65 63 61 74  nes are deprecat
22920 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c  ed. Use the [sql
22930 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d  ite3_trace_v2()]
22940 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e   interface.** in
22950 73 74 65 61 64 20 6f 66 20 74 68 65 20 72 6f 75  stead of the rou
22960 74 69 6e 65 73 20 64 65 73 63 72 69 62 65 64 20  tines described 
22970 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  here..**.** Thes
22980 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
22990 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
229a0 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
229b0 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
229c0 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
229d0 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
229e0 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
229f0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
22a00 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
22a10 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
22a20 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
22a30 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a   is invoked at.*
22a40 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20  * various times 
22a50 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  when an SQL stat
22a60 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72  ement is being r
22a70 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  un by [sqlite3_s
22a80 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  tep()]..** ^The 
22a90 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
22aa0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
22ab0 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38  ked with a UTF-8
22ac0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
22ad0 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  e.** SQL stateme
22ae0 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73  nt text as the s
22af0 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
22b00 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e  egins executing.
22b10 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c  .** ^(Additional
22b20 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
22b30 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74   callbacks might
22b40 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63   occur.** as eac
22b50 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70  h triggered subp
22b60 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65  rogram is entere
22b70 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  d.  The callback
22b80 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a  s for triggers.*
22b90 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d  * contain a UTF-
22ba0 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68  8 SQL comment th
22bb0 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68  at identifies th
22bc0 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a  e trigger.)^.**.
22bd0 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** The [SQLITE_T
22be0 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d  RACE_SIZE_LIMIT]
22bf0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
22c00 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
22c10 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65   to limit.** the
22c20 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e   length of [boun
22c30 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70  d parameter] exp
22c40 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75  ansion in the ou
22c50 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  tput of sqlite3_
22c60 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  trace()..**.** ^
22c70 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
22c80 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
22c90 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66   by sqlite3_prof
22ca0 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ile() is invoked
22cb0 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20  .** as each SQL 
22cc0 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
22cd0 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  es.  ^The profil
22ce0 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
22cf0 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  ins.** the origi
22d00 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  nal statement te
22d10 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61  xt and an estima
22d20 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b  te of wall-clock
22d30 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20   time.** of how 
22d40 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d  long that statem
22d50 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e  ent took to run.
22d60 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
22d70 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20  allback.** time 
22d80 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e  is in units of n
22d90 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65  anoseconds, howe
22da0 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  ver the current 
22db0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
22dc0 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c  * is only capabl
22dd0 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  e of millisecond
22de0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74   resolution so t
22df0 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67  he six least sig
22e00 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69  nificant.** digi
22e10 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61  ts in the time a
22e20 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20  re meaningless. 
22e30 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
22e40 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69   of SQLite.** mi
22e50 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61  ght provide grea
22e60 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f  ter resolution o
22e70 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63  n the profiler c
22e80 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a  allback.  The.**
22e90 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
22ea0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
22eb0 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69  onsidered experi
22ec0 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a  mental and is.**
22ed0 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
22ee0 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ge in future ver
22ef0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
22f00 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  .*/.SQLITE_DEPRE
22f10 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69  CATED void *sqli
22f20 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
22f30 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54 72  3*,.   void(*xTr
22f40 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
22f50 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
22f60 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
22f70 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  ED void *sqlite3
22f80 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33  _profile(sqlite3
22f90 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f  *,.   void(*xPro
22fa0 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  file)(void*,cons
22fb0 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
22fc0 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b  uint64), void*);
22fd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22fe0 3a 20 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e  : SQL Trace Even
22ff0 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
23000 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43  RDS: SQLITE_TRAC
23010 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  E.**.** These co
23020 6e 73 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79  nstants identify
23030 20 63 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e   classes of even
23040 74 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d  ts that can be m
23050 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e  onitored.** usin
23060 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  g the [sqlite3_t
23070 72 61 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69  race_v2()] traci
23080 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 74  ng logic.  The t
23090 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
230a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   to [sqlite3_tra
230b0 63 65 5f 76 32 28 29 5d 20 69 73 20 61 6e 20 4f  ce_v2()] is an O
230c0 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  R-ed combination
230d0 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
230e0 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
230f0 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20  ing constants.  
23100 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
23110 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65  ent to the trace
23120 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
23130 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
23140 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a  wing constants..
23150 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e  **.** New tracin
23160 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20  g constants may 
23170 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
23180 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a  re releases..**.
23190 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c  ** ^A trace call
231a0 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20 61 72  back has four ar
231b0 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61  guments: xCallba
231c0 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20  ck(T,C,P,X)..** 
231d0 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20  ^The T argument 
231e0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e  is one of the in
231f0 74 65 67 65 72 20 74 79 70 65 20 63 6f 64 65 73  teger type codes
23200 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20   above..** ^The 
23210 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  C argument is a 
23220 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
23230 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61 73 73  ext pointer pass
23240 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
23250 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
23260 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  to [sqlite3_trac
23270 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  e_v2()]..** The 
23280 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74  P and X argument
23290 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77  s are pointers w
232a0 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65  hose meanings de
232b0 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a  pend on T..**.**
232c0 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
232d0 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c  E_TRACE_STMT]] <
232e0 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  dt>SQLITE_TRACE_
232f0 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  STMT</dt>.** <dd
23300 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43  >^An SQLITE_TRAC
23310 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20  E_STMT callback 
23320 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
23330 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
23340 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62 65  ment.** first be
23350 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  gins running and
23360 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f 74 68   possibly at oth
23370 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e 67 20  er times during 
23380 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e  the.** execution
23390 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64   of the prepared
233a0 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75 63 68   statement, such
233b0 20 61 73 20 61 74 20 74 68 65 20 73 74 61 72 74   as at the start
233c0 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72 69 67   of each.** trig
233d0 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 20  ger subprogram. 
233e0 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
233f0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
23400 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
23410 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68   statement]. ^Th
23420 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e X argument is 
23430 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73  a pointer to a s
23440 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69  tring which.** i
23450 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64 65 64  s the unexpanded
23460 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74 68 65   SQL text of the
23470 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
23480 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f  ent or an SQL co
23490 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69  mment .** that i
234a0 6e 64 69 63 61 74 65 73 20 74 68 65 20 69 6e 76  ndicates the inv
234b0 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74 72 69  ocation of a tri
234c0 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c  gger.  ^The call
234d0 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65  back can compute
234e0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 65 78  .** the same tex
234f0 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  t that would hav
23500 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 20  e been returned 
23510 62 79 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  by the legacy [s
23520 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 0a  qlite3_trace()].
23530 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  ** interface by 
23540 75 73 69 6e 67 20 74 68 65 20 58 20 61 72 67 75  using the X argu
23550 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65 67 69  ment when X begi
23560 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61 6e 64  ns with "--" and
23570 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71   invoking.** [sq
23580 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
23590 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69 73 65  ql(P)] otherwise
235a0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
235b0 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d  _TRACE_PROFILE]]
235c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
235d0 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a  E_PROFILE</dt>.*
235e0 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45  * <dd>^An SQLITE
235f0 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63  _TRACE_PROFILE c
23600 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64 65 73  allback provides
23610 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 74   approximately t
23620 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72  he same.** infor
23630 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70 72 6f  mation as is pro
23640 76 69 64 65 64 20 62 79 20 74 68 65 20 5b 73 71  vided by the [sq
23650 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d  lite3_profile()]
23660 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54   callback..** ^T
23670 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
23680 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
23690 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
236a0 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a  ement] and the.*
236b0 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  * X argument poi
236c0 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69 74 20  nts to a 64-bit 
236d0 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
236e0 20 74 68 65 20 65 73 74 69 6d 61 74 65 64 20 6f   the estimated o
236f0 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  f.** the number 
23700 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68  of nanosecond th
23710 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  at the prepared 
23720 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74  statement took t
23730 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53  o run..** ^The S
23740 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46  QLITE_TRACE_PROF
23750 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ILE callback is 
23760 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
23770 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
23780 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  hes..**.** [[SQL
23790 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20  ITE_TRACE_ROW]] 
237a0 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45  <dt>SQLITE_TRACE
237b0 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ROW</dt>.** <dd
237c0 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43  >^An SQLITE_TRAC
237d0 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69  E_ROW callback i
237e0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  s invoked whenev
237f0 65 72 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a  er a prepared.**
23800 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72   statement gener
23810 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20 72 6f  ates a single ro
23820 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a  w of result.  .*
23830 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  * ^The P argumen
23840 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
23850 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
23860 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74  statement] and t
23870 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74  he.** X argument
23880 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a   is unused..**.*
23890 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  * [[SQLITE_TRACE
238a0 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c  _CLOSE]] <dt>SQL
238b0 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c  ITE_TRACE_CLOSE<
238c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20  /dt>.** <dd>^An 
238d0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f  SQLITE_TRACE_CLO
238e0 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  SE callback is i
238f0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 64 61  nvoked when a da
23900 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
23910 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20  tion closes..** 
23920 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
23930 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
23940 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
23950 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74  nnection] object
23960 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20 61 72  .** and the X ar
23970 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64  gument is unused
23980 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ..** </dl>.*/.#d
23990 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
239a0 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20 30 78  CE_STMT       0x
239b0 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
239c0 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20  E_TRACE_PROFILE 
239d0 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20     0x02.#define 
239e0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57  SQLITE_TRACE_ROW
239f0 20 20 20 20 20 20 20 20 30 78 30 34 0a 23 64 65          0x04.#de
23a00 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43  fine SQLITE_TRAC
23a10 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30 78 30  E_CLOSE      0x0
23a20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  8../*.** CAPI3RE
23a30 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48 6f 6f  F: SQL Trace Hoo
23a40 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  k.** METHOD: sql
23a50 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
23a60 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
23a70 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,M,X,P) interf
23a80 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
23a90 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  trace callback.*
23aa0 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61 67 61  * function X aga
23ab0 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65 20 63  inst [database c
23ac0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73  onnection] D, us
23ad0 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d 61 73  ing property mas
23ae0 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65  k M.** and conte
23af0 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e  xt pointer P.  ^
23b00 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62 61 63  If the X callbac
23b10 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20  k is.** NULL or 
23b20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20 69 73  if the M mask is
23b30 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 61 63   zero, then trac
23b40 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ing is disabled.
23b50 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d    The.** M argum
23b60 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
23b70 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65 64 20  e bitwise OR-ed 
23b80 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
23b90 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b  * zero or more [
23ba0 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20 63 6f  SQLITE_TRACE] co
23bb0 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  nstants..**.** ^
23bc0 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65 69 74  Each call to eit
23bd0 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63  her sqlite3_trac
23be0 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74  e() or sqlite3_t
23bf0 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72 72 69  race_v2() overri
23c00 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73  des .** (cancels
23c10 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c  ) any prior call
23c20 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61  s to sqlite3_tra
23c30 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  ce() or sqlite3_
23c40 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  trace_v2()..**.*
23c50 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62 61 63  * ^The X callbac
23c60 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
23c70 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74 68 65  never any of the
23c80 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69 66 69   events identifi
23c90 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d  ed by .** mask M
23ca0 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20 69 6e   occur.  ^The in
23cb0 74 65 67 65 72 20 72 65 74 75 72 6e 20 76 61 6c  teger return val
23cc0 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c  ue from the call
23cd0 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e 74 6c  back is currentl
23ce0 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68  y.** ignored, th
23cf0 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20 63 68  ough this may ch
23d00 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 72  ange in future r
23d10 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c 62 61  eleases.  Callba
23d20 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ck.** implementa
23d30 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65 74  tions should ret
23d40 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75  urn zero to ensu
23d50 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70 61 74  re future compat
23d60 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ibility..**.** ^
23d70 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  A trace callback
23d80 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
23d90 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a   four arguments:
23da0 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c   callback(T,C,P,
23db0 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72  X)..** ^The T ar
23dc0 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
23dd0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41   the [SQLITE_TRA
23de0 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73  CE].** constants
23df0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 79   to indicate why
23e00 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61   the callback wa
23e10 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54  s invoked..** ^T
23e20 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73  he C argument is
23e30 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63   a copy of the c
23e40 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a  ontext pointer..
23e50 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 61  ** The P and X a
23e60 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69  rguments are poi
23e70 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e  nters whose mean
23e80 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54  ings depend on T
23e90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
23ea0 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 69  te3_trace_v2() i
23eb0 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
23ec0 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63 65 20  nded to replace 
23ed0 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
23ee0 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
23ef0 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64 20 5b  3_trace()] and [
23f00 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
23f10 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68 69 63  )], both of whic
23f20 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65 63 61  h.** are depreca
23f30 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ted..*/.int sqli
23f40 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a 20 20  te3_trace_v2(.  
23f50 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69  sqlite3*,.  unsi
23f60 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e  gned uMask,.  in
23f70 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e  t(*xCallback)(un
23f80 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69  signed,void*,voi
23f90 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69  d*,void*),.  voi
23fa0 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a  d *pCtx.);../*.*
23fb0 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
23fc0 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
23fd0 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
23fe0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
23ff0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  he sqlite3_progr
24000 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c  ess_handler(D,N,
24010 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63  X,P) interface c
24020 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61  auses the callba
24030 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
24040 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70   to be invoked p
24050 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
24060 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
24070 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
24080 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
24090 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
240a0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  nd [sqlite3_get_
240b0 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20  table()] for.** 
240c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
240d0 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70  ion D.  An examp
240e0 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a  le use for this.
240f0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
24100 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
24110 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
24120 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
24130 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72  * ^The parameter
24140 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72   P is passed thr
24150 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79  ough as the only
24160 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
24170 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  e .** callback f
24180 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65  unction X.  ^The
24190 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20   parameter N is 
241a0 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20  the approximate 
241b0 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76  number of .** [v
241c0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69  irtual machine i
241d0 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61  nstructions] tha
241e0 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t are evaluated 
241f0 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69  between successi
24200 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  ve.** invocation
24210 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  s of the callbac
24220 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c  k X.  ^If N is l
24230 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65  ess than one the
24240 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a  n the progress.*
24250 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73  * handler is dis
24260 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  abled..**.** ^On
24270 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
24280 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79  ress handler may
24290 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f   be defined at o
242a0 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b  ne time per.** [
242b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
242c0 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20  ion]; setting a 
242d0 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e  new progress han
242e0 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65  dler cancels the
242f0 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53  .** old one.  ^S
24300 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72  etting parameter
24310 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62   X to NULL disab
24320 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73  les the progress
24330 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68   handler..** ^Th
24340 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
24350 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62  er is also disab
24360 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e  led by setting N
24370 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73   to a value less
24380 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a  .** than 1..**.*
24390 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65  * ^If the progre
243a0 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
243b0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
243c0 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
243d0 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
243e0 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
243f0 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
24400 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
24410 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
24420 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61  GUI progress dia
24430 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54  log box..**.** T
24440 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
24450 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  ler callback mus
24460 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
24470 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
24480 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
24490 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
244a0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
244b0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
244c0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
244d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
244e0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
244f0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
24500 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
24510 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24520 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
24530 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
24540 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
24550 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71  h..**.*/.void sq
24560 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
24570 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
24580 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
24590 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
245a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
245b0 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
245c0 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
245d0 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20  ** CONSTRUCTOR: 
245e0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
245f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
24600 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
24610 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70  abase file as sp
24620 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ecified by the .
24630 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
24640 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e  ment. ^The filen
24650 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
24660 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
24670 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
24680 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
24690 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
246a0 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
246b0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
246c0 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
246d0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
246e0 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63   ^(A [database c
246f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
24700 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
24710 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
24720 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
24730 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
24740 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
24750 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
24760 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
24770 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
24780 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
24790 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
247a0 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
247b0 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
247c0 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
247d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
247e0 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
247f0 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65  ject.)^ ^(If the
24800 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
24810 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
24820 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
24830 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
24840 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
24850 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
24860 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
24870 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54  s returned.)^ ^T
24880 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
24890 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
248a0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
248b0 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
248c0 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
248d0 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
248e0 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
248f0 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  on of the error 
24900 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
24910 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ure of any.** of
24920 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   the sqlite3_ope
24930 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  n() routines..**
24940 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
24950 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62   encoding will b
24960 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61  e UTF-8 for data
24970 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73  bases created us
24980 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  ing.** sqlite3_o
24990 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
249a0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68  _open_v2().  ^Th
249b0 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
249c0 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73  ng for databases
249d0 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e  .** created usin
249e0 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  g sqlite3_open16
249f0 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31  () will be UTF-1
24a00 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
24a10 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a  byte order..**.*
24a20 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
24a30 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
24a40 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
24a50 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
24a60 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
24a70 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
24a80 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
24a90 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
24aa0 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
24ab0 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
24ac0 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
24ad0 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
24ae0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
24af0 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
24b00 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
24b10 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
24b20 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
24b30 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
24b40 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
24b50 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
24b60 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
24b70 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
24b80 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
24b90 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65  nnection.  ^(The
24ba0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
24bb0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   to.** sqlite3_o
24bc0 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b  pen_v2() can tak
24bd0 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
24be0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
24bf0 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
24c00 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
24c10 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
24c20 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
24c30 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
24c40 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  LMUTEX], [SQLITE
24c50 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
24c60 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  E],.** [SQLITE_O
24c70 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
24c80 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ], and/or [SQLIT
24c90 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
24ca0 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
24cb0 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
24cc0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
24cd0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
24ce0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
24cf0 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
24d00 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
24d10 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
24d20 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
24d30 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
24d40 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
24d50 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
24d60 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
24d70 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
24d80 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
24d90 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
24da0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
24db0 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
24dc0 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
24dd0 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
24de0 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
24df0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
24e00 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
24e10 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
24e20 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
24e30 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
24e40 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
24e50 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
24e60 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
24e70 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
24e80 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
24e90 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
24ea0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
24eb0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
24ec0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
24ed0 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
24ee0 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20  reated if.** it 
24ef0 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
24f00 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
24f10 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
24f20 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
24f30 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
24f40 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
24f50 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
24f60 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  >)^.** </dl>.**.
24f70 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
24f80 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
24f90 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
24fa0 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
24fb0 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
24fc0 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f  hown above optio
24fd0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
24fe0 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51  ith other.** [SQ
24ff0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
25000 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e  LY | SQLITE_OPEN
25010 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e  _* bits].** then
25020 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
25030 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
25040 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
25050 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
25060 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65  flag is set, the
25070 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
25080 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65  onnection.** ope
25090 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d  ns in the multi-
250a0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
250b0 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20  g mode] as long 
250c0 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68  as the single-th
250d0 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73  read.** mode has
250e0 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74   not been set at
250f0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
25100 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49   start-time.  ^I
25110 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
25120 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
25130 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
25140 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
25150 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
25160 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
25170 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
25180 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
25190 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
251a0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
251b0 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
251c0 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
251d0 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ime..** ^The [SQ
251e0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
251f0 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
25200 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
25210 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65  connection to be
25220 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20  .** eligible to 
25230 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68  use [shared cach
25240 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c  e mode], regardl
25250 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
25260 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20  r not shared.** 
25270 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
25280 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
25290 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
252a0 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a  che()].  ^The.**
252b0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
252c0 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
252d0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
252e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
252f0 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63  to not.** partic
25300 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64  ipate in [shared
25310 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65   cache mode] eve
25320 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c  n if it is enabl
25330 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
25340 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
25350 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
25360 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
25370 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
25380 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
25390 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
253a0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
253b0 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
253c0 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
253d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
253e0 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66  should use.  ^If
253f0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
25400 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
25410 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
25420 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
25430 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
25440 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
25450 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
25460 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
25470 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
25480 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
25490 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
254a0 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
254b0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
254c0 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
254d0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
254e0 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
254f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
25500 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
25510 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
25520 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
25530 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
25540 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
25550 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
25560 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
25570 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
25580 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
25590 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
255a0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
255b0 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
255c0 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
255d0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
255e0 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
255f0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
25600 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
25610 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
25620 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
25630 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
25640 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
25650 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
25660 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
25670 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
25680 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
25690 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
256a0 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
256b0 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
256c0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
256d0 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
256e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
256f0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
25700 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  d..**.** [[URI f
25710 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69  ilenames in sqli
25720 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33  te3_open()]] <h3
25730 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f  >URI Filenames</
25740 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55  h3>.**.** ^If [U
25750 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74  RI filename] int
25760 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
25770 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20  nabled, and the 
25780 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
25790 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68  t.** begins with
257a0 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74   "file:", then t
257b0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69  he filename is i
257c0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
257d0 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c  URI. ^URI.** fil
257e0 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
257f0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20  tion is enabled 
25800 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
25810 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
25820 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66  .** set in the f
25830 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
25840 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
25850 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61  2(), or if it ha
25860 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65  s.** been enable
25870 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67  d globally using
25880 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
25890 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20  FIG_URI] option 
258a0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  with the.** [sql
258b0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d  ite3_config()] m
258c0 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20  ethod or by the 
258d0 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
258e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
258f0 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53  tion..** As of S
25900 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
25910 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d  7.7, URI filenam
25920 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
25930 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a   is turned off.*
25940 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75  * by default, bu
25950 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  t future release
25960 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
25970 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c  t enable URI fil
25980 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72  ename.** interpr
25990 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75  etation by defau
259a0 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66  lt.  See "[URI f
259b0 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61  ilenames]" for a
259c0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
259d0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
259e0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  URI filenames ar
259f0 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69  e parsed accordi
25a00 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20  ng to RFC 3986. 
25a10 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74  ^If the URI cont
25a20 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f  ains an.** autho
25a30 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75  rity, then it mu
25a40 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20  st be either an 
25a50 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
25a60 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22  the string .** "
25a70 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20  localhost". ^If 
25a80 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73  the authority is
25a90 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74   not an empty st
25aa0 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f  ring or "localho
25ab0 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f  st", an .** erro
25ac0 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f  r is returned to
25ad0 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68   the caller. ^Th
25ae0 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f  e fragment compo
25af0 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69  nent of a URI, i
25b00 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69  f .** present, i
25b10 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
25b20 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
25b30 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74  e path component
25b40 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74   of the URI as t
25b50 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
25b60 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63  isk file.** whic
25b70 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  h contains the d
25b80 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65  atabase. ^If the
25b90 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74   path begins wit
25ba0 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65  h a '/' characte
25bb0 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  r, .** then it i
25bc0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
25bd0 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
25be0 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  h. ^If the path 
25bf0 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a  does not begin .
25c00 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d  ** with a '/' (m
25c10 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20  eaning that the 
25c20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f  authority sectio
25c30 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  n is omitted fro
25c40 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68  m the URI).** th
25c50 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69  en the path is i
25c60 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
25c70 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a  relative path. .
25c80 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c  ** ^(On windows,
25c90 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f   the first compo
25ca0 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c  nent of an absol
25cb0 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20  ute path .** is 
25cc0 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63  a drive specific
25cd0 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22  ation (e.g. "C:"
25ce0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72  ).)^.**.** [[cor
25cf0 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61  e URI query para
25d00 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20  meters]].** The 
25d10 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
25d20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e  of a URI may con
25d30 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tain parameters 
25d40 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72  that are interpr
25d50 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62  eted.** either b
25d60 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c  y SQLite itself,
25d70 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20   or by a [VFS | 
25d80 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65  custom VFS imple
25d90 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53  mentation]..** S
25da0 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75  QLite and its bu
25db0 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69  ilt-in [VFSes] i
25dc0 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20  nterpret the.** 
25dd0 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20  following query 
25de0 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a  parameters:.**.*
25df0 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e  * <ul>.**   <li>
25e00 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68   <b>vfs</b>: ^Th
25e10 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65  e "vfs" paramete
25e20 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  r may be used to
25e30 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d   specify the nam
25e40 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46  e of.**     a VF
25e50 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72  S object that pr
25e60 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61  ovides the opera
25e70 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
25e80 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c  rface that shoul
25e90 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64  d.**     be used
25ea0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
25eb0 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20  atabase file on 
25ec0 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f  disk. ^If this o
25ed0 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a  ption is set to.
25ee0 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20  **     an empty 
25ef0 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75  string the defau
25f00 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73  lt VFS object is
25f10 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69   used. ^Specifyi
25f20 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a  ng an unknown.**
25f30 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65       VFS is an e
25f40 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65  rror. ^If sqlite
25f50 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
25f60 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20  sed and the vfs 
25f70 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
25f80 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74   present, then t
25f90 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64  he VFS specified
25fa0 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74   by the option t
25fb0 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20  akes precedence 
25fc0 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20  over.**     the 
25fd0 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
25fe0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
25ff0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
26000 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
26010 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c     <li> <b>mode<
26020 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20  /b>: ^(The mode 
26030 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
26040 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
26050 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20  ro", "rw",.**   
26060 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d    "rwc", or "mem
26070 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67  ory". Attempting
26080 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e   to set it to an
26090 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73  y other value is
260a0 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72  .**     an error
260b0 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20  )^. .**     ^If 
260c0 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65  "ro" is specifie
260d0 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  d, then the data
260e0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
260f0 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a  or read-only .**
26100 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73       access, jus
26110 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c  t as if the [SQL
26120 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
26130 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e  Y] flag had been
26140 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20   set in the .** 
26150 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65      third argume
26160 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
26170 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65  en_v2(). ^If the
26180 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20   mode option is 
26190 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22  set to .**     "
261a0 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61  rw", then the da
261b0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
261c0 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20   for read-write 
261d0 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29  (but not create)
261e0 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
261f0 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50   as if SQLITE_OP
26200 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75  EN_READWRITE (bu
26210 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45  t not SQLITE_OPE
26220 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a  N_CREATE) had .*
26230 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20  *     been set. 
26240 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20  ^Value "rwc" is 
26250 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
26260 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20  tting both .**  
26270 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52     SQLITE_OPEN_R
26280 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c  EADWRITE and SQL
26290 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e  ITE_OPEN_CREATE.
262a0 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f    ^If the mode o
262b0 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
262c0 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20  set to "memory" 
262d0 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d  then a pure [in-
262e0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d  memory database]
262f0 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64   that never read
26300 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74  s.**     or writ
26310 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20  es from disk is 
26320 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20  used. ^It is an 
26330 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79  error to specify
26340 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20   a value for.** 
26350 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72      the mode par
26360 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c  ameter that is l
26370 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20  ess restrictive 
26380 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66  than that specif
26390 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68  ied by.**     th
263a0 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69  e flags passed i
263b0 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
263c0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
263d0 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
263e0 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68  *   <li> <b>cach
263f0 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68  e</b>: ^The cach
26400 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
26410 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
26420 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20   "shared" or.** 
26430 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e      "private". ^
26440 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73  Setting it to "s
26450 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61  hared" is equiva
26460 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
26470 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  the.**     SQLIT
26480 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
26490 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c  HE bit in the fl
264a0 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ags argument pas
264b0 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71  sed to.**     sq
264c0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
264d0 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61   ^Setting the ca
264e0 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  che parameter to
264f0 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a   "private" is .*
26500 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74  *     equivalent
26510 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20   to setting the 
26520 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
26530 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a  ATECACHE bit..**
26540 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33       ^If sqlite3
26550 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
26560 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68  ed and the "cach
26570 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e" parameter is 
26580 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20  present in.**   
26590 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65    a URI filename
265a0 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72  , its value over
265b0 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69  rides any behavi
265c0 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20  or requested by 
265d0 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53  setting.**     S
265e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
265f0 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54  TECACHE or SQLIT
26600 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
26610 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20  HE flag..**.**  
26620 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e  <li> <b>psow</b>
26630 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61  : ^The psow para
26640 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20  meter indicates 
26650 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
26660 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72  he.**     [power
26670 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20  safe overwrite] 
26680 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72  property does or
26690 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20   does not apply 
266a0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74  to the.**     st
266b0 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77  orage media on w
266c0 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73  hich the databas
266d0 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a  e file resides..
266e0 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e  **.**  <li> <b>n
266f0 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20  olock</b>: ^The 
26700 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72  nolock parameter
26710 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
26720 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ery parameter.**
26730 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65       which if se
26740 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20  t disables file 
26750 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62  locking in rollb
26760 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65  ack journal mode
26770 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20  s.  This.**     
26780 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63  is useful for ac
26790 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61  cessing a databa
267a0 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74  se on a filesyst
267b0 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  em that does not
267c0 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20  .**     support 
267d0 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f  locking.  Cautio
267e0 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72  n:  Database cor
267f0 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ruption might re
26800 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20  sult if two.**  
26810 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65     or more proce
26820 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68  sses write to th
26830 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
26840 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74  and any one of t
26850 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63  hose.**     proc
26860 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63  esses uses noloc
26870 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  k=1..**.**  <li>
26880 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62   <b>immutable</b
26890 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c  >: ^The immutabl
268a0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  e parameter is a
268b0 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a   boolean query.*
268c0 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20  *     parameter 
268d0 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74  that indicates t
268e0 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
268f0 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20   file is stored 
26900 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f  on.**     read-o
26910 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65  nly media.  ^Whe
26920 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73  n immutable is s
26930 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d  et, SQLite assum
26940 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20  es that the.**  
26950 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65     database file
26960 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
26970 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72  ed, even by a pr
26980 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65  ocess with highe
26990 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65  r.**     privile
269a0 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64  ge, and so the d
269b0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
269c0 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20  d read-only and 
269d0 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20  all locking.**  
269e0 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65     and change de
269f0 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62  tection is disab
26a00 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53  led.  Caution: S
26a10 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74  etting the immut
26a20 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70  able.**     prop
26a30 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61  erty on a databa
26a40 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65  se file that doe
26a50 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65  s in fact change
26a60 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20   can result.**  
26a70 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20     in incorrect 
26a80 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e  query results an
26a90 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52  d/or [SQLITE_COR
26aa0 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a  RUPT] errors..**
26ab0 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b       See also: [
26ac0 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
26ad0 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20  UTABLE]..**     
26ae0 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a    .** </ul>.**.*
26af0 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  * ^Specifying an
26b00 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74   unknown paramet
26b10 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  er in the query 
26b20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
26b30 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20  RI is not an.** 
26b40 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76  error.  Future v
26b50 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
26b60 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61  e might understa
26b70 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75  nd additional qu
26b80 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
26b90 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20  s.  See "[query 
26ba0 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20  parameters with 
26bb0 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20  special meaning 
26bc0 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a  to SQLite]" for.
26bd0 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
26be0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
26bf0 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20   [[URI filename 
26c00 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55  examples]] <h3>U
26c10 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
26c20 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ples</h3>.**.** 
26c30 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
26c40 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63  " align=center c
26c50 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a  ellpadding=5>.**
26c60 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69   <tr><th> URI fi
26c70 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73  lenames <th> Res
26c80 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ults.** <tr><td>
26c90 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74   file:data.db <t
26ca0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
26cb0 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
26cc0 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
26cd0 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
26ce0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
26cf0 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
26d00 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20  ta.db<br>.**    
26d10 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f        file:///ho
26d20 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
26d30 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <br> .**        
26d40 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f    file://localho
26d50 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  st/home/fred/dat
26d60 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a  a.db <br> <td> .
26d70 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
26d80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
26d90 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
26da0 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e  ata.db"..** <tr>
26db0 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b  <td> file://dark
26dc0 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  star/home/fred/d
26dd0 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
26de0 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
26df0 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73  r. "darkstar" is
26e00 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65   not a recognize
26e10 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20  d authority..** 
26e20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77  <tr><td style="w
26e30 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61  hite-space:nowra
26e40 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  p"> .**         
26e50 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75   file:///C:/Docu
26e60 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65  ments%20and%20Se
26e70 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b  ttings/fred/Desk
26e80 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20  top/data.db.**  
26e90 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20     <td> Windows 
26ea0 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66  only: Open the f
26eb0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e  ile "data.db" on
26ec0 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20   fred's desktop 
26ed0 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20  on drive.**     
26ee0 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68       C:. Note th
26ef0 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70  at the %20 escap
26f00 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d  ing in this exam
26f10 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63  ple is not stric
26f20 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  tly .**         
26f30 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61   necessary - spa
26f40 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61  ce characters ca
26f50 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61  n be used litera
26f60 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lly.**          
26f70 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  in URI filenames
26f80 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
26f90 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
26fa0 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65  ro&cache=private
26fb0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
26fc0 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61     Open file "da
26fd0 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
26fe0 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20  rrent directory 
26ff0 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63  for read-only ac
27000 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20  cess..**        
27010 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20    Regardless of 
27020 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
27030 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65  hared-cache mode
27040 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a   is enabled by.*
27050 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
27060 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74  lt, use a privat
27070 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e  e cache..** <tr>
27080 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
27090 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73  fred/data.db?vfs
270a0 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74  =unix-dotfile <t
270b0 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
270c0 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
270d0 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
270e0 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
270f0 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65  FS "unix-dotfile
27100 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ".**          th
27110 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65  at uses dot-file
27120 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f  s in place of po
27130 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63  six advisory loc
27140 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  king..** <tr><td
27150 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
27160 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64  ode=readonly <td
27170 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
27180 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e  n error. "readon
27190 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c  ly" is not a val
271a0 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68  id option for th
271b0 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74  e "mode" paramet
271c0 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  er..** </table>.
271d0 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64  **.** ^URI hexad
271e0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
271f0 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72  quences (%HH) ar
27200 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  e supported with
27210 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a  in the path and.
27220 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  ** query compone
27230 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20  nts of a URI. A 
27240 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
27250 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73  pe sequence cons
27260 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72  ists of a.** per
27270 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20  cent sign - "%" 
27280 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78  - followed by ex
27290 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65  actly two hexade
272a0 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a  cimal digits .**
272b0 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f   specifying an o
272c0 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66  ctet value. ^Bef
272d0 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20  ore the path or 
272e0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
272f0 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c   of a.** URI fil
27300 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70  ename are interp
27310 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20  reted, they are 
27320 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
27330 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20  F-8 and all .** 
27340 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
27350 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70  pe sequences rep
27360 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c  laced by a singl
27370 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e  e byte containin
27380 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70  g the.** corresp
27390 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66  onding octet. If
273a0 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65   this process ge
273b0 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c  nerates an inval
273c0 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  id UTF-8 encodin
273d0 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  g,.** the result
273e0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
273f0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
27400 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
27410 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
27420 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
27430 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
27440 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
27450 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
27460 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
27470 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
27480 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
27490 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
274a0 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
274b0 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
274c0 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
274d0 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
274e0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
274f0 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
27500 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
27510 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
27520 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
27530 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
27540 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
27550 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
27560 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
27570 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
27580 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
27590 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
275a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
275b0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
275c0 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  2().  Otherwise,
275d0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
275e0 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
275f0 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
27600 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
27610 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   fail..**.** See
27620 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
27630 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a  temp_directory].
27640 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
27650 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
27660 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
27670 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
27680 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
27690 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
276a0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
276b0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
276c0 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
276d0 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
276e0 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
276f0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
27700 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
27710 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
27720 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
27730 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
27740 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
27750 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
27760 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
27770 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
27780 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
27790 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
277a0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
277b0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
277c0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
277d0 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
277e0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
277f0 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
27800 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
27810 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
27820 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
27830 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
27840 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
27850 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50  Values For URI P
27860 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
27870 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74  These are utilit
27880 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66  y routines, usef
27890 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d  ul to VFS implem
278a0 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20  entations, that 
278b0 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20  check.** to see 
278c0 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69  if a database fi
278d0 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61  le was a URI tha
278e0 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70  t contained a sp
278f0 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a  ecific query .**
27900 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20   parameter, and 
27910 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68  if so obtains th
27920 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
27930 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e  query parameter.
27940 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74  .**.** If F is t
27950 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
27960 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
27970 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
27980 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a  en() method of .
27990 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65  ** a VFS impleme
279a0 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  ntation when the
279b0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
279c0 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20   to xOpen() has 
279d0 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20  one or .** more 
279e0 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  of the [SQLITE_O
279f0 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c  PEN_URI] or [SQL
27a00 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
27a10 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a  ] bits set and.*
27a20 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20  * P is the name 
27a30 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
27a40 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ameter, then.** 
27a50 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
27a60 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
27a70 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
27a80 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74  the P.** paramet
27a90 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20  er if it exists 
27aa0 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
27ab0 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20  r if P does not 
27ac0 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20  appear as a .** 
27ad0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
27ae0 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61  on F.  If P is a
27af0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
27b00 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20   of F.** has no 
27b10 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20  explicit value, 
27b20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
27b30 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
27b40 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69  returns.** a poi
27b50 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79  nter to an empty
27b60 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
27b70 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
27b80 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
27b90 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68  utine assumes th
27ba0 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61  at P is a boolea
27bb0 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61  n.** parameter a
27bc0 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  nd returns true 
27bd0 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29  (1) or false (0)
27be0 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68   according to th
27bf0 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e  e value.** of P.
27c00 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72    The sqlite3_ur
27c10 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
27c20 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
27c30 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65   true (1) if the
27c40 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65  .** value of que
27c50 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
27c60 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20  s one of "yes", 
27c70 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20  "true", or "on" 
27c80 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f  in any.** case o
27c90 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  r if the value b
27ca0 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e  egins with a non
27cb0 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54  -zero number.  T
27cc0 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  he .** sqlite3_u
27cd0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
27ce0 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  ) routines retur
27cf0 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20  ns false (0) if 
27d00 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
27d10 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
27d20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22  P is one of "no"
27d30 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f  , "false", or "o
27d40 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20  ff" in any case 
27d50 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c  or.** if the val
27d60 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
27d70 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20   numeric zero.  
27d80 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75  If P is not a qu
27d90 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
27da0 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20   on F or if the 
27db0 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f  value of P is do
27dc0 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79  es not match any
27dd0 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65   of the.** above
27de0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
27df0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
27e00 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29  ) returns (B!=0)
27e10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
27e20 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c  te3_uri_int64(F,
27e30 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e  P,D) routine con
27e40 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20  verts the value 
27e50 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36  of P into a.** 6
27e60 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
27e70 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eger and returns
27e80 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f   that integer, o
27e90 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  r D if P does no
27ea0 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20  t.** exist.  If 
27eb0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
27ec0 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  s something othe
27ed0 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65  r than an intege
27ee0 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20  r, then.** zero 
27ef0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
27f00 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55  .** If F is a NU
27f10 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
27f20 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
27f30 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
27f40 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20  rns NULL and.** 
27f50 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
27f60 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
27f70 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e  ns B.  If F is n
27f80 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ot a NULL pointe
27f90 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20  r and.** is not 
27fa0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
27fb0 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72  pathname pointer
27fc0 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73   that SQLite pas
27fd0 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
27fe0 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64  en.** VFS method
27ff0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
28000 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
28010 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
28020 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a   and probably.**
28030 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
28040 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
28050 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
28060 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
28070 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
28080 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69  char *zParam);.i
28090 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  nt sqlite3_uri_b
280a0 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61  oolean(const cha
280b0 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20  r *zFile, const 
280c0 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e  char *zParam, in
280d0 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c  t bDefault);.sql
280e0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
280f0 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e  e3_uri_int64(con
28100 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20  st char*, const 
28110 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  char*, sqlite3_i
28120 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt64);.../*.** C
28130 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
28140 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
28150 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
28160 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ite3.**.** ^If t
28170 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73  he most recent s
28180 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
28190 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  l associated wit
281a0 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  h .** [database 
281b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61  connection] D fa
281c0 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73  iled, then the s
281d0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44  qlite3_errcode(D
281e0 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  ) interface.** r
281f0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
28200 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
28210 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65   or [extended re
28220 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
28230 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e  hat.** API call.
28240 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20  .** If the most 
28250 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
28260 77 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a  was successful,.
28270 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
28280 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
28290 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
282a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
282b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
282c0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
282d0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
282e0 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
282f0 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
28300 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
28310 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
28320 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
28330 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
28340 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
28350 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  sabled..**.** ^T
28360 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
28370 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
28380 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
28390 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
283a0 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
283b0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
283c0 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
283d0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
283e0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
283f0 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
28400 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
28410 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
28420 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
28430 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
28440 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
28450 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74  d to worry about
28460 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73   freeing the res
28470 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ult..** However,
28480 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
28490 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77  g might be overw
284a0 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
284b0 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73  cated by.** subs
284c0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
284d0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
284e0 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73  erface functions
284f0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
28500 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20  qlite3_errstr() 
28510 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
28520 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61  s the English-la
28530 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74  nguage text.** t
28540 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
28550 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c  e [result code],
28560 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28   as UTF-8..** ^(
28570 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
28580 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
28590 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
285a0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  ed internally.**
285b0 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65   and must not be
285c0 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70   freed by the ap
285d0 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a  plication)^..**.
285e0 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69  ** When the seri
285f0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
28600 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73  g mode] is in us
28610 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  e, it might be t
28620 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20  he.** case that 
28630 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f  a second error o
28640 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72  ccurs on a separ
28650 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65  ate thread in be
28660 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d  tween.** the tim
28670 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65  e of the first e
28680 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c  rror and the cal
28690 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  l to these inter
286a0 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  faces..** When t
286b0 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65  hat happens, the
286c0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69   second error wi
286d0 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73  ll be reported s
286e0 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e  ince these.** in
286f0 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20  terfaces always 
28700 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20  report the most 
28710 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20  recent result.  
28720 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73  To avoid.** this
28730 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61  , each thread ca
28740 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69  n obtain exclusi
28750 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  ve use of the [d
28760 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
28770 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f  on] D.** by invo
28780 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
28790 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69  tex_enter]([sqli
287a0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
287b0 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69  ) before beginni
287c0 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61  ng.** to use D a
287d0 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  nd invoking [sql
287e0 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
287f0 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
28800 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a  tex](D)) after.*
28810 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74  * all calls to t
28820 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69  he interfaces li
28830 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f  sted here are co
28840 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mpleted..**.** I
28850 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
28860 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
28870 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
28880 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
28890 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
288a0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
288b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
288c0 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
288d0 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
288e0 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
288f0 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
28900 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  set..*/.int sqli
28910 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
28920 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71  te3 *db);.int sq
28930 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
28940 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
28950 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  db);.const char 
28960 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
28970 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
28980 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
28990 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
289a0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
289b0 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e  qlite3_errstr(in
289c0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
289d0 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74  REF: Prepared St
289e0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
289f0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
28a00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
28a10 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
28a20 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
28a30 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
28a40 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
28a50 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
28a60 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a  statement that.*
28a70 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69  * has been compi
28a80 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20  led into binary 
28a90 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64  form and is read
28aa0 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  y to be evaluate
28ab0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f  d..**.** Think o
28ac0 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  f each SQL state
28ad0 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61  ment as a separa
28ae0 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67  te computer prog
28af0 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69  ram.  The.** ori
28b00 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69  ginal SQL text i
28b10 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
28b20 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  A prepared state
28b30 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20  ment object .** 
28b40 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20  is the compiled 
28b50 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c  object code.  Al
28b60 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f  l SQL must be co
28b70 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a  nverted into a.*
28b80 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
28b90 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63  ment before it c
28ba0 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  an be run..**.**
28bb0 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20   The life-cycle 
28bc0 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74  of a prepared st
28bd0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
28be0 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65  sually goes like
28bf0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
28c00 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
28c10 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
28c20 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
28c30 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
28c40 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  epare_v2()]..** 
28c50 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
28c60 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d   to [parameters]
28c70 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
28c80 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
28c90 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
28ca0 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
28cb0 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
28cc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
28cd0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
28ce0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
28cf0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
28d00 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
28d10 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
28d20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
28d30 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
28d40 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
28d50 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
28d60 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
28d70 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
28d80 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
28d90 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  )]..** </ol>.*/.
28da0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
28db0 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
28dc0 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
28dd0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
28de0 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45  ime Limits.** ME
28df0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
28e00 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
28e10 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
28e20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
28e30 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
28e40 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
28e50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
28e60 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
28e70 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
28e80 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
28e90 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
28ea0 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
28eb0 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
28ec0 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
28ed0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
28ee0 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
28ef0 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
28f00 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
28f10 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
28f20 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
28f30 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
28f40 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
28f50 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
28f60 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
28f70 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a  construct.)^.**.
28f80 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
28f90 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
28fa0 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
28fb0 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
28fc0 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68  d..** ^(For each
28fd0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
28fe0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e  SQLITE_LIMIT_<i>
28ff0 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69  NAME</i> there i
29000 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
29010 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
29020 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f  nd].** set at co
29030 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20  mpile-time by a 
29040 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
29050 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b  acro called.** [
29060 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
29070 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d  MAX_<i>NAME</i>]
29080 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
29090 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
290a0 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
290b0 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
290c0 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
290d0 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
290e0 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
290f0 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
29100 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
29110 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
29120 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e  r bound..**.** ^
29130 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
29140 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
29150 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67   limit was chang
29160 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ed, the .** [sql
29170 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  ite3_limit()] in
29180 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
29190 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
291a0 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a  of the limit..**
291b0 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64   ^Hence, to find
291c0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
291d0 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69  ue of a limit wi
291e0 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69  thout changing i
291f0 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76  t,.** simply inv
29200 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61  oke this interfa
29210 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72  ce with the thir
29220 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
29230 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  to -1..**.** Run
29240 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
29250 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
29260 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
29270 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
29280 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
29290 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
292a0 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
292b0 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
292c0 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
292d0 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
292e0 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
292f0 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
29300 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
29310 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
29320 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
29330 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
29340 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
29350 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
29360 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
29370 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
29380 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
29390 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
293a0 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
293b0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
293c0 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
293d0 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
293e0 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
293f0 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
29400 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
29410 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
29420 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
29430 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
29440 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
29450 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
29460 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
29470 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
29480 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
29490 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
294a0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
294b0 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
294c0 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
294d0 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
294e0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
294f0 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
29500 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
29510 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
29520 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
29530 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
29540 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
29550 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
29560 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
29570 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
29580 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
29590 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73  leases..*/.int s
295a0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
295b0 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
295c0 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
295d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
295e0 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
295f0 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  gories.** KEYWOR
29600 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
29610 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74  ory} {*limit cat
29620 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54  egories}.**.** T
29630 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
29640 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65  efine various pe
29650 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73  rformance limits
29660 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
29670 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74  lowered at run-t
29680 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ime using [sqlit
29690 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20  e3_limit()]..** 
296a0 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20  The synopsis of 
296b0 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  the meanings of 
296c0 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69  the various limi
296d0 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f  ts is shown belo
296e0 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  w..** Additional
296f0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
29700 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69  available at [li
29710 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e  mits | Limits in
29720 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20   SQLite]..**.** 
29730 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
29740 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20  _LIMIT_LENGTH]] 
29750 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
29760 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
29770 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29780 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
29790 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
297a0 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79  table row, in by
297b0 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  tes.<dd>)^.**.**
297c0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
297d0 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  SQL_LENGTH]] ^(<
297e0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
297f0 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
29800 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
29810 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
29820 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69  SQL statement, i
29830 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a  n bytes.</dd>)^.
29840 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29850 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28  IMIT_COLUMN]] ^(
29860 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
29870 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
29880 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29890 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
298a0 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
298b0 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
298c0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
298d0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
298e0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
298f0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
29900 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
29910 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
29920 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
29930 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  se.</dd>)^.**.**
29940 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
29950 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  EXPR_DEPTH]] ^(<
29960 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
29970 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
29980 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
29990 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
299a0 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
299b0 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
299c0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
299d0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
299e0 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64  ND_SELECT]] ^(<d
299f0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
29a00 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
29a10 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
29a20 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
29a30 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
29a40 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
29a50 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
29a60 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29a70 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c  IT_VDBE_OP]] ^(<
29a80 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
29a90 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20  VDBE_OP</dt>.** 
29aa0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29ab0 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75  number of instru
29ac0 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74  ctions in a virt
29ad0 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67  ual machine prog
29ae0 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69  ram.** used to i
29af0 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20  mplement an SQL 
29b00 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 5b  statement.  If [
29b10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
29b20 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 74 68 65 20  v2()] or.** the 
29b30 65 71 75 69 76 61 6c 65 6e 74 20 74 72 69 65 73  equivalent tries
29b40 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 73 70 61   to allocate spa
29b50 63 65 20 66 6f 72 20 6d 6f 72 65 20 74 68 61 6e  ce for more than
29b60 20 74 68 69 73 20 6d 61 6e 79 20 6f 70 63 6f 64   this many opcod
29b70 65 73 0a 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c  es.** in a singl
29b80 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
29b90 6d 65 6e 74 2c 20 61 6e 20 53 51 4c 49 54 45 5f  ment, an SQLITE_
29ba0 4e 4f 4d 45 4d 20 65 72 72 6f 72 20 69 73 20 72  NOMEM error is r
29bb0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
29bc0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29bd0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
29be0 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  G]] ^(<dt>SQLITE
29bf0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
29c00 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
29c10 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
29c20 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
29c30 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
29c40 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
29c50 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
29c60 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  HED]] ^(<dt>SQLI
29c70 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
29c80 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
29c90 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
29ca0 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
29cb0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
29cc0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
29cd0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
29ce0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
29cf0 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  TH]].** ^(<dt>SQ
29d00 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
29d10 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
29d20 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
29d30 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
29d40 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
29d50 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
29d60 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
29d70 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
29d80 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29d90 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
29da0 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c  _NUMBER]].** ^(<
29db0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
29dc0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
29dd0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
29de0 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
29df0 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
29e00 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
29e10 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
29e20 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
29e30 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
29e40 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
29e50 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
29e60 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
29e70 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
29e80 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
29e90 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
29ea0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
29eb0 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
29ec0 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74  _THREADS]] ^(<dt
29ed0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f  >SQLITE_LIMIT_WO
29ee0 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74  RKER_THREADS</dt
29ef0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29f00 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
29f10 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20  uxiliary worker 
29f20 74 68 72 65 61 64 73 20 74 68 61 74 20 61 20 73  threads that a s
29f30 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72  ingle.** [prepar
29f40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61  ed statement] ma
29f50 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a  y start.</dd>)^.
29f60 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
29f70 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29f80 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
29f90 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
29fa0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29fb0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
29fc0 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
29fd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29fe0 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
29ff0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
2a000 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2a010 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
2a020 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
2a030 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2a040 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
2a050 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
2a060 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a070 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
2a080 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a090 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
2a0a0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
2a0b0 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
2a0c0 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
2a0d0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
2a0e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a0f0 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
2a100 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
2a110 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
2a120 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
2a130 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
2a140 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
2a150 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
2a160 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
2a170 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  ER_DEPTH        
2a180 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
2a190 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
2a1a0 45 52 5f 54 48 52 45 41 44 53 20 20 20 20 20 20  ER_THREADS      
2a1b0 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43       11../*.** C
2a1c0 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65  API3REF: Prepare
2a1d0 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Flags.**.** The
2a1e0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
2a1f0 69 6e 65 20 76 61 72 69 6f 75 73 20 66 6c 61 67  ine various flag
2a200 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 61  s that can be pa
2a210 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 22 70 72  ssed into.** "pr
2a220 65 70 46 6c 61 67 73 22 20 70 61 72 61 6d 65 74  epFlags" paramet
2a230 65 72 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  er of the [sqlit
2a240 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
2a250 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2a260 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
2a270 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 0a   interfaces..**.
2a280 2a 2a 20 4e 65 77 20 66 6c 61 67 73 20 6d 61 79  ** New flags may
2a290 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
2a2a0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
2a2b0 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64  SQLite..**.** <d
2a2c0 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50  l>.** [[SQLITE_P
2a2d0 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e  REPARE_PERSISTEN
2a2e0 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
2a2f0 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54  _PREPARE_PERSIST
2a300 45 4e 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ENT</dt>.** <dd>
2a310 54 68 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41  The SQLITE_PREPA
2a320 52 45 5f 50 45 52 53 49 53 54 45 4e 54 20 66 6c  RE_PERSISTENT fl
2a330 61 67 20 69 73 20 61 20 68 69 6e 74 20 74 6f 20  ag is a hint to 
2a340 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65  the query planne
2a350 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
2a360 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a370 20 77 69 6c 6c 20 62 65 20 72 65 74 61 69 6e 65   will be retaine
2a380 64 20 66 6f 72 20 61 20 6c 6f 6e 67 20 74 69 6d  d for a long tim
2a390 65 20 61 6e 64 0a 2a 2a 20 70 72 6f 62 61 62 6c  e and.** probabl
2a3a0 79 20 72 65 75 73 65 64 20 6d 61 6e 79 20 74 69  y reused many ti
2a3b0 6d 65 73 2e 29 5e 20 5e 57 69 74 68 6f 75 74 20  mes.)^ ^Without 
2a3c0 74 68 69 73 20 66 6c 61 67 2c 20 5b 73 71 6c 69  this flag, [sqli
2a3d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2a3e0 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2a3f0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2a400 5d 20 61 73 73 75 6d 65 20 74 68 61 74 20 74 68  ] assume that th
2a410 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2a420 6d 65 6e 74 20 77 69 6c 6c 20 0a 2a 2a 20 62 65  ment will .** be
2a430 20 75 73 65 64 20 6a 75 73 74 20 6f 6e 63 65 20   used just once 
2a440 6f 72 20 61 74 20 6d 6f 73 74 20 61 20 66 65 77  or at most a few
2a450 20 74 69 6d 65 73 20 61 6e 64 20 74 68 65 6e 20   times and then 
2a460 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67 0a  destroyed using.
2a470 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2a480 6c 69 7a 65 28 29 5d 20 72 65 6c 61 74 69 76 65  lize()] relative
2a490 6c 79 20 73 6f 6f 6e 2e 20 54 68 65 20 63 75 72  ly soon. The cur
2a4a0 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
2a4b0 69 6f 6e 20 61 63 74 73 0a 2a 2a 20 6f 6e 20 74  ion acts.** on t
2a4c0 68 69 73 20 68 69 6e 74 20 62 79 20 61 76 6f 69  his hint by avoi
2a4d0 64 69 6e 67 20 74 68 65 20 75 73 65 20 6f 66 20  ding the use of 
2a4e0 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
2a4f0 79 5d 20 73 6f 20 61 73 20 6e 6f 74 20 74 6f 0a  y] so as not to.
2a500 2a 2a 20 64 65 70 6c 65 74 65 20 74 68 65 20 6c  ** deplete the l
2a510 69 6d 69 74 65 64 20 73 74 6f 72 65 20 6f 66 20  imited store of 
2a520 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
2a530 2e 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e  . Future version
2a540 73 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  s of.** SQLite m
2a550 61 79 20 61 63 74 20 6f 6e 20 74 68 69 73 20 68  ay act on this h
2a560 69 6e 74 20 64 69 66 66 65 72 65 6e 74 6c 79 2e  int differently.
2a570 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
2a580 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 45 50  fine SQLITE_PREP
2a590 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 20 20  ARE_PERSISTENT  
2a5a0 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 31              0x01
2a5b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a5c0 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
2a5d0 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
2a5e0 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
2a5f0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
2a600 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
2a610 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55  lite3.** CONSTRU
2a620 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74  CTOR: sqlite3_st
2a630 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  mt.**.** To exec
2a640 75 74 65 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ute an SQL state
2a650 6d 65 6e 74 2c 20 69 74 20 6d 75 73 74 20 66 69  ment, it must fi
2a660 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
2a670 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
2a680 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
2a690 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
2a6a0 6f 75 74 69 6e 65 73 2e 20 20 4f 72 2c 20 69 6e  outines.  Or, in
2a6b0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2a6c0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2a6d0 61 72 65 20 63 6f 6e 73 74 72 75 63 74 6f 72 73  are constructors
2a6e0 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
2a6f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
2a700 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ject..**.** The 
2a710 70 72 65 66 65 72 72 65 64 20 72 6f 75 74 69 6e  preferred routin
2a720 65 20 74 6f 20 75 73 65 20 69 73 20 5b 73 71 6c  e to use is [sql
2a730 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2a740 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  )].  The.** [sql
2a750 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2a760 69 6e 74 65 72 66 61 63 65 20 69 73 20 6c 65 67  interface is leg
2a770 61 63 79 20 61 6e 64 20 73 68 6f 75 6c 64 20 62  acy and should b
2a780 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 20 5b 73  e avoided..** [s
2a790 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2a7a0 33 28 29 5d 20 68 61 73 20 61 6e 20 65 78 74 72  3()] has an extr
2a7b0 61 20 22 70 72 65 70 46 6c 61 67 73 22 20 6f 70  a "prepFlags" op
2a7c0 74 69 6f 6e 20 74 68 61 74 20 69 73 20 75 73 65  tion that is use
2a7d0 64 0a 2a 2a 20 66 6f 72 20 73 70 65 63 69 61 6c  d.** for special
2a7e0 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
2a7f0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
2a800 55 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65 73  UTF-8 interfaces
2a810 20 69 73 20 70 72 65 66 65 72 72 65 64 2c 20 61   is preferred, a
2a820 73 20 53 51 4c 69 74 65 20 63 75 72 72 65 6e 74  s SQLite current
2a830 6c 79 0a 2a 2a 20 64 6f 65 73 20 61 6c 6c 20 70  ly.** does all p
2a840 61 72 73 69 6e 67 20 75 73 69 6e 67 20 55 54 46  arsing using UTF
2a850 2d 38 2e 20 20 54 68 65 20 55 54 46 2d 31 36 20  -8.  The UTF-16 
2a860 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
2a870 72 6f 76 69 64 65 64 0a 2a 2a 20 61 73 20 61 20  rovided.** as a 
2a880 63 6f 6e 76 65 6e 69 65 6e 63 65 2e 20 20 54 68  convenience.  Th
2a890 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72 66 61  e UTF-16 interfa
2a8a0 63 65 73 20 77 6f 72 6b 20 62 79 20 63 6f 6e 76  ces work by conv
2a8b0 65 72 74 69 6e 67 20 74 68 65 0a 2a 2a 20 69 6e  erting the.** in
2a8c0 70 75 74 20 74 65 78 74 20 69 6e 74 6f 20 55 54  put text into UT
2a8d0 46 2d 38 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 69  F-8, then invoki
2a8e0 6e 67 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ng the correspon
2a8f0 64 69 6e 67 20 55 54 46 2d 38 20 69 6e 74 65 72  ding UTF-8 inter
2a900 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  face..**.** The 
2a910 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
2a920 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
2a930 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2a940 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
2a950 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73  .** prior succes
2a960 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
2a970 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2a980 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2a990 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2a9a0 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68  3_open16()].  Th
2a9b0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2a9c0 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68  ction must not h
2a9d0 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e  ave been closed.
2a9e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
2a9f0 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
2aa00 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
2aa10 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
2aa20 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
2aa30 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
2aa40 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
2aa50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2aa60 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ), sqlite3_prepa
2aa70 72 65 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20  re_v2(),.** and 
2aa80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2aa90 76 33 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v3().** interfac
2aaa0 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
2aab0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2aac0 65 31 36 28 29 2c 20 73 71 6c 69 74 65 33 5f 70  e16(), sqlite3_p
2aad0 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a  repare16_v2(),.*
2aae0 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  * and sqlite3_pr
2aaf0 65 70 61 72 65 31 36 5f 76 33 28 29 20 75 73 65  epare16_v3() use
2ab00 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
2ab10 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
2ab20 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76  ument is negativ
2ab30 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  e, then zSql is 
2ab40 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
2ab50 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
2ab60 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
2ab70 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20  te is positive, 
2ab80 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a  then it is the.*
2ab90 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
2aba0 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
2abb0 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  .  ^If nByte is 
2abc0 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72  zero, then no pr
2abd0 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
2abe0 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64  ent is generated
2abf0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c  ..** If the call
2ac00 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68  er knows that th
2ac10 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
2ac20 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
2ac30 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ted, then.** the
2ac40 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65  re is a small pe
2ac50 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
2ac60 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61  age to passing a
2ac70 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
2ac80 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65  r that.** is the
2ac90 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2aca0 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
2acb0 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
2acc0 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
2acd0 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a  -terminator..**.
2ace0 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
2acf0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
2ad00 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
2ad10 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
2ad20 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
2ad30 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
2ad40 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
2ad50 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
2ad60 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
2ad70 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
2ad80 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
2ad90 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
2ada0 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
2adb0 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
2adc0 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
2add0 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
2ade0 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
2adf0 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
2ae00 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
2ae10 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
2ae20 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
2ae30 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2ae40 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
2ae50 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
2ae60 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
2ae70 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
2ae80 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
2ae90 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
2aea0 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
2aeb0 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
2aec0 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
2aed0 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
2aee0 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
2aef0 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
2af00 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
2af10 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
2af20 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
2af30 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
2af40 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
2af50 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
2af60 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
2af70 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
2af80 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
2af90 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
2afa0 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
2afb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
2afc0 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
2afd0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
2afe0 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
2aff0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
2b000 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
2b010 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2b020 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2c  e3_prepare_v2(),
2b030 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2b040 5f 76 33 28 29 2c 20 73 71 6c 69 74 65 33 5f 70  _v3(), sqlite3_p
2b050 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a  repare16_v2(),.*
2b060 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  * and sqlite3_pr
2b070 65 70 61 72 65 31 36 5f 76 33 28 29 20 69 6e 74  epare16_v3() int
2b080 65 72 66 61 63 65 73 20 61 72 65 20 72 65 63 6f  erfaces are reco
2b090 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
2b0a0 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 0a 2a 2a  new programs..**
2b0b0 20 54 68 65 20 6f 6c 64 65 72 20 69 6e 74 65 72   The older inter
2b0c0 66 61 63 65 73 20 28 73 71 6c 69 74 65 33 5f 70  faces (sqlite3_p
2b0d0 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c  repare() and sql
2b0e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2b0f0 29 0a 2a 2a 20 61 72 65 20 72 65 74 61 69 6e 65  ).** are retaine
2b100 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
2b110 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62  compatibility, b
2b120 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20  ut their use is 
2b130 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20  discouraged..** 
2b140 5e 49 6e 20 74 68 65 20 22 76 58 22 20 69 6e 74  ^In the "vX" int
2b150 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
2b160 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
2b170 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
2b180 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
2b190 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
2b1a0 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
2b1b0 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
2b1c0 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
2b1d0 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
2b1e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
2b1f0 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
2b200 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79  have differently
2b210 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a   in three ways:.
2b220 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
2b230 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  i>.** ^If the da
2b240 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
2b250 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
2b260 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
2b270 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
2b280 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
2b290 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
2b2a0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
2b2b0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
2b2c0 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
2b2d0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
2b2e0 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
2b2f0 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b  in. As many as [
2b300 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d  SQLITE_MAX_SCHEM
2b310 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72  A_RETRY].** retr
2b320 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62  ies will occur b
2b330 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74  efore sqlite3_st
2b340 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e  ep() gives up an
2b350 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72  d returns an err
2b360 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  or..** </li>.**.
2b370 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e  ** <li>.** ^When
2b380 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
2b390 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
2b3a0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
2b3b0 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
2b3c0 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
2b3d0 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
2b3e0 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
2b3f0 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61  ^The legacy beha
2b400 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
2b410 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2b420 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
2b430 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
2b440 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
2b450 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
2b460 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2b470 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
2b480 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
2b490 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2b4a0 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65  et()].** in orde
2b4b0 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
2b4c0 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
2b4d0 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
2b4e0 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
2b4f0 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
2b500 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
2b510 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
2b520 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
2b530 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
2b540 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
2b550 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
2b560 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62  specific value b
2b570 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74  ound to [paramet
2b580 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65  er | host parame
2b590 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20  ter] in the .** 
2b5a0 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67  WHERE clause mig
2b5b0 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
2b5c0 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
2b5d0 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
2b5e0 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74  ement,.** then t
2b5f0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  he statement wil
2b600 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
2b610 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61  ly recompiled, a
2b620 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
2b630 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61  een .** a schema
2b640 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20   change, on the 
2b650 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f  first  [sqlite3_
2b660 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c  step()] call fol
2b670 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67  lowing any chang
2b680 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  e.** to the [sql
2b690 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
2b6a0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
2b6b0 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20  at [parameter]. 
2b6c0 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69  .** ^The specifi
2b6d0 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45  c value of WHERE
2b6e0 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74  -clause [paramet
2b6f0 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  er] might influe
2b700 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69  nce the .** choi
2b710 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
2b720 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2b730 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61  r is the left-ha
2b740 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49  nd side of a [LI
2b750 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d  KE].** or [GLOB]
2b760 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20   operator or if 
2b770 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
2b780 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20   compared to an 
2b790 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a  indexed column.*
2b7a0 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54  * and the [SQLIT
2b7b0 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20  E_ENABLE_STAT3] 
2b7c0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
2b7d0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
2b7e0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
2b7f0 70 3e 5e 73 71 6c 69 74 65 33 5f 70 72 65 70 61  p>^sqlite3_prepa
2b800 72 65 5f 76 33 28 29 20 64 69 66 66 65 72 73 20  re_v3() differs 
2b810 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 70 72 65  from sqlite3_pre
2b820 70 61 72 65 5f 76 32 28 29 20 6f 6e 6c 79 20 69  pare_v2() only i
2b830 6e 20 68 61 76 69 6e 67 0a 2a 2a 20 74 68 65 20  n having.** the 
2b840 65 78 74 72 61 20 70 72 65 70 46 6c 61 67 73 20  extra prepFlags 
2b850 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63 68  parameter, which
2b860 20 69 73 20 61 20 62 69 74 20 61 72 72 61 79 20   is a bit array 
2b870 63 6f 6e 73 69 73 74 69 6e 67 20 6f 66 20 7a 65  consisting of ze
2b880 72 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 6f 66  ro or.** more of
2b890 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 50 52 45   the [SQLITE_PRE
2b8a0 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 7c  PARE_PERSISTENT|
2b8b0 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 2a  SQLITE_PREPARE_*
2b8c0 5d 20 66 6c 61 67 73 2e 20 20 5e 54 68 65 0a 2a  ] flags.  ^The.*
2b8d0 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
2b8e0 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  e_v2() interface
2b8f0 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 74   works exactly t
2b900 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71  he same as.** sq
2b910 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2b920 28 29 20 77 69 74 68 20 61 20 7a 65 72 6f 20 70  () with a zero p
2b930 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d 65 74  repFlags paramet
2b940 65 72 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  er..** </ol>.*/.
2b950 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
2b960 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
2b970 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2b980 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2b990 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2b9a0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
2b9b0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2b9c0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
2b9d0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2b9e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2b9f0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2ba00 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2ba10 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2ba20 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2ba30 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2ba40 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2ba50 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
2ba60 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2ba70 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2ba80 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2ba90 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
2baa0 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
2bab0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2bac0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2bad0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2bae0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
2baf0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2bb00 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
2bb10 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2bb20 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2bb30 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2bb40 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2bb50 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
2bb60 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2bb70 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2bb80 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2bb90 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
2bba0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2bbb0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2bbc0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2bbd0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
2bbe0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2bbf0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2bc00 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2bc10 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2bc20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2bc30 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2bc40 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2bc50 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
2bc60 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2bc70 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2bc80 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2bc90 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2bca0 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72   unsigned int pr
2bcb0 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f  epFlags, /* Zero
2bcc0 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f   or more SQLITE_
2bcd0 50 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a  PREPARE_ flags *
2bce0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2bcf0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2bd00 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2bd10 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2bd20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
2bd30 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2bd40 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2bd50 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2bd60 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
2bd70 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74  epare16(.  sqlit
2bd80 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2bd90 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2bda0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2bdb0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
2bdc0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2bdd0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
2bde0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2bdf0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2be00 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2be10 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2be20 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
2be30 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2be40 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2be50 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2be60 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
2be70 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2be80 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2be90 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2bea0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
2beb0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2bec0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2bed0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2bee0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2bef0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2bf00 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2bf10 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2bf20 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
2bf30 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2bf40 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2bf50 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2bf60 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2bf70 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2bf80 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2bf90 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2bfa0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2bfb0 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
2bfc0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2bfd0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2bfe0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2bff0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
2c000 70 61 72 65 31 36 5f 76 33 28 0a 20 20 73 71 6c  pare16_v3(.  sql
2c010 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2c020 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2c030 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2c040 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
2c050 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2c060 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
2c070 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2c080 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2c090 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2c0a0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2c0b0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69  bytes. */.  unsi
2c0c0 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46 61 6c  gned int prepFal
2c0d0 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d  gs, /* Zero or m
2c0e0 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41  ore SQLITE_PREPA
2c0f0 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73  RE_ flags */.  s
2c100 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2c110 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2c120 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2c130 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2c140 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2c150 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2c160 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2c170 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
2c180 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2c190 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
2c1a0 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44  nt SQL.** METHOD
2c1b0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2c1c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2c1d0 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61  3_sql(P) interfa
2c1e0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2c1f0 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 79 20 6f  nter to a copy o
2c200 66 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20 53  f the UTF-8.** S
2c210 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20  QL text used to 
2c220 63 72 65 61 74 65 20 5b 70 72 65 70 61 72 65 64  create [prepared
2c230 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 20 69 66   statement] P if
2c240 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 61 74 65   P was.** create
2c250 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  d by [sqlite3_pr
2c260 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
2c270 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2c280 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2c290 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2c2a0 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  , or [sqlite3_pr
2c2b0 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a  epare16_v3()]..*
2c2c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
2c2d0 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 20 69  xpanded_sql(P) i
2c2e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2c2f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2c300 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
2c310 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 53  containing the S
2c320 51 4c 20 74 65 78 74 20 6f 66 20 70 72 65 70 61  QL text of prepa
2c330 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20  red statement P 
2c340 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70  with.** [bound p
2c350 61 72 61 6d 65 74 65 72 73 5d 20 65 78 70 61 6e  arameters] expan
2c360 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
2c370 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 20 70   example, if a p
2c380 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c390 74 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69  t is created usi
2c3a0 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65  ng the SQL.** te
2c3b0 78 74 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c  xt "SELECT $abc,
2c3c0 3a 78 79 7a 22 20 61 6e 64 20 69 66 20 70 61 72  :xyz" and if par
2c3d0 61 6d 65 74 65 72 20 24 61 62 63 20 69 73 20 62  ameter $abc is b
2c3e0 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67 65 72 20  ound to integer 
2c3f0 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61  2345.** and para
2c400 6d 65 74 65 72 20 3a 78 79 7a 20 69 73 20 75 6e  meter :xyz is un
2c410 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69  bound, then sqli
2c420 74 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72  te3_sql() will r
2c430 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69  eturn.** the ori
2c440 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20 22 53  ginal string, "S
2c450 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22  ELECT $abc,:xyz"
2c460 20 62 75 74 20 73 71 6c 69 74 65 33 5f 65 78 70   but sqlite3_exp
2c470 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77  anded_sql().** w
2c480 69 6c 6c 20 72 65 74 75 72 6e 20 22 53 45 4c 45  ill return "SELE
2c490 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e  CT 2345,NULL".)^
2c4a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2c4b0 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2c4c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2c4d0 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73  urns NULL if ins
2c4e0 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
2c4f0 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61 62 6c 65  .** is available
2c500 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
2c510 75 6c 74 2c 20 6f 72 20 69 66 20 74 68 65 20 72  ult, or if the r
2c520 65 73 75 6c 74 20 77 6f 75 6c 64 20 65 78 63 65  esult would exce
2c530 65 64 20 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61  ed the.** the ma
2c540 78 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e  ximum string len
2c550 67 74 68 20 64 65 74 65 72 6d 69 6e 65 64 20 62  gth determined b
2c560 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49  y the [SQLITE_LI
2c570 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a  MIT_LENGTH]..**.
2c580 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
2c590 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
2c5a0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
2c5b0 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65  ption limits the
2c5c0 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e   size of.** boun
2c5d0 64 20 70 61 72 61 6d 65 74 65 72 20 65 78 70 61  d parameter expa
2c5e0 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53  nsions.  ^The [S
2c5f0 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45  QLITE_OMIT_TRACE
2c600 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
2c610 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73 65 73 20  * option causes 
2c620 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2c630 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77 61 79 73  _sql() to always
2c640 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a   return NULL..**
2c650 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20  .** ^The string 
2c660 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2c670 74 65 33 5f 73 71 6c 28 50 29 20 69 73 20 6d 61  te3_sql(P) is ma
2c680 6e 61 67 65 64 20 62 79 20 53 51 4c 69 74 65 20  naged by SQLite 
2c690 61 6e 64 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  and is.** automa
2c6a0 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20 77 68  tically freed wh
2c6b0 65 6e 20 74 68 65 20 70 72 65 70 61 72 65 64 20  en the prepared 
2c6c0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e  statement is fin
2c6d0 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  alized..** ^The 
2c6e0 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20  string returned 
2c6f0 62 79 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  by sqlite3_expan
2c700 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e 20 74  ded_sql(P), on t
2c710 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c 0a 2a  he other hand,.*
2c720 2a 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72  * is obtained fr
2c730 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2c740 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73 74 20 62  oc()] and must b
2c750 65 20 66 72 65 65 20 62 79 20 74 68 65 20 61 70  e free by the ap
2c760 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62 79 20  plication.** by 
2c770 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
2c780 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
2c790 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2c7a0 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
2c7b0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2c7c0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65  .char *sqlite3_e
2c7d0 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69  xpanded_sql(sqli
2c7e0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2c7f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c800 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
2c810 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2c820 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61   Writes The Data
2c830 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  base.** METHOD: 
2c840 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2c850 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2c860 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29  stmt_readonly(X)
2c870 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2c880 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
2c890 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  o) if.** and onl
2c8a0 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72  y if the [prepar
2c8b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
2c8c0 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20  makes no direct 
2c8d0 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68  changes to.** th
2c8e0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2c8f0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
2c900 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2c910 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2c920 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2c930 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75  ns] or.** [virtu
2c940 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74  al tables] might
2c950 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2c960 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20  base indirectly 
2c970 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74  as a side effect
2c980 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .  .** ^(For exa
2c990 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c  mple, if an appl
2c9a0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20  ication defines 
2c9b0 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c  a function "eval
2c9c0 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c  ()" that .** cal
2c9d0 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ls [sqlite3_exec
2c9e0 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  ()], then the fo
2c9f0 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74  llowing SQL stat
2ca00 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63  ement would.** c
2ca10 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
2ca20 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20  se file through 
2ca30 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a  side-effects:.**
2ca40 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2ca50 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45  <pre>.**    SELE
2ca60 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20  CT eval('DELETE 
2ca70 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74  FROM t1') FROM t
2ca80 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  2;.** </pre></bl
2ca90 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
2caa0 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20  But because the 
2cab0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2cac0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nt does not chan
2cad0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
2cae0 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79  file.** directly
2caf0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  , sqlite3_stmt_r
2cb00 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20  eadonly() would 
2cb10 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75  still return tru
2cb20 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e  e.)^.**.** ^Tran
2cb30 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20  saction control 
2cb40 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20  statements such 
2cb50 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d  as [BEGIN], [COM
2cb60 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d  MIT], [ROLLBACK]
2cb70 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d  ,.** [SAVEPOINT]
2cb80 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20  , and [RELEASE] 
2cb90 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74  cause sqlite3_st
2cba0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
2cbb0 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a   return true,.**
2cbc0 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65   since the state
2cbd0 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
2cbe0 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   do not actually
2cbf0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
2cc00 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68  base but.** rath
2cc10 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20  er they control 
2cc20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68  the timing of wh
2cc30 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65  en other stateme
2cc40 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a  nts modify the .
2cc50 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54  ** database.  ^T
2cc60 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20  he [ATTACH] and 
2cc70 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65  [DETACH] stateme
2cc80 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a  nts also cause.*
2cc90 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
2cca0 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
2ccb0 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20  urn true since, 
2ccc0 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74  while those stat
2ccd0 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65  ements.** change
2cce0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
2ccf0 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  on of a database
2cd00 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65   connection, the
2cd10 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a  y do not make .*
2cd20 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  * changes to the
2cd30 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2cd40 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
2cd50 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65 20  n disk..** ^The 
2cd60 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2cd70 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66 61 63  donly() interfac
2cd80 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 66  e returns true f
2cd90 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e 63 65  or [BEGIN] since
2cda0 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65 72 65  .** [BEGIN] mere
2cdb0 6c 79 20 73 65 74 73 20 69 6e 74 65 72 6e 61 6c  ly sets internal
2cdc0 20 66 6c 61 67 73 2c 20 62 75 74 20 74 68 65 20   flags, but the 
2cdd0 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 49 4d 4d  [BEGIN|BEGIN IMM
2cde0 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b  EDIATE] and.** [
2cdf0 42 45 47 49 4e 7c 42 45 47 49 4e 20 45 58 43 4c  BEGIN|BEGIN EXCL
2ce00 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64 73 20  USIVE] commands 
2ce10 64 6f 20 74 6f 75 63 68 20 74 68 65 20 64 61 74  do touch the dat
2ce20 61 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a 2a 20  abase and so.** 
2ce30 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2ce40 64 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e 73 20  donly() returns 
2ce50 66 61 6c 73 65 20 66 6f 72 20 74 68 6f 73 65 20  false for those 
2ce60 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 69 6e 74  commands..*/.int
2ce70 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2ce80 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73  adonly(sqlite3_s
2ce90 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2cea0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2ceb0 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65  termine If A Pre
2cec0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2ced0 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a  Has Been Reset.*
2cee0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2cef0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2cf00 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
2cf10 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65  usy(S) interface
2cf20 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
2cf30 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a  on-zero) if the.
2cf40 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2cf50 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65  tement] S has be
2cf60 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65  en stepped at le
2cf70 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a  ast once using .
2cf80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2cf90 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65 69  (S)] but has nei
2cfa0 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70  ther run to comp
2cfb0 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 64  letion (returned
2cfc0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
2cfd0 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  ] from [sqlite3_
2cfe0 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a  step(S)]) nor.**
2cff0 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e   been reset usin
2d000 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2d010 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  (S)].  ^The sqli
2d020 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
2d030 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
2d040 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53  turns false if S
2d050 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2d060 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74  er.  If S is not
2d070 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e   a .** NULL poin
2d080 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ter and is not a
2d090 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
2d0a0 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  lid [prepared st
2d0b0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
2d0c0 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ct, then the beh
2d0d0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2d0e0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
2d0f0 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a  undesirable..**.
2d100 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
2d110 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  e can be used in
2d120 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71   combination [sq
2d130 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
2d140 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20  )].** to locate 
2d150 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61  all prepared sta
2d160 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
2d170 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ed with a databa
2d180 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  se .** connectio
2d190 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65  n that are in ne
2d1a0 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65  ed of being rese
2d1b0 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20  t.  This can be 
2d1c0 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61  used,.** for exa
2d1d0 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73  mple, in diagnos
2d1e0 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tic routines to 
2d1f0 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61  search for prepa
2d200 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  red .** statemen
2d210 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64  ts that are hold
2d220 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
2d230 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  n open..*/.int s
2d240 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
2d250 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2d260 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d270 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
2d280 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
2d290 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
2d2a0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d2b0 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
2d2c0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2d2d0 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
2d2e0 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
2d2f0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
2d300 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
2d310 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
2d320 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
2d330 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
2d340 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
2d350 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
2d360 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
2d370 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
2d380 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
2d390 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2d3a0 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
2d3b0 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
2d3c0 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
2d3d0 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
2d3e0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
2d3f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2d400 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
2d410 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
2d420 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
2d430 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
2d440 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
2d450 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2d460 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
2d470 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
2d480 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
2d490 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
2d4a0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
2d4b0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
2d4c0 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
2d4d0 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
2d4e0 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
2d4f0 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
2d500 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
2d510 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
2d520 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2d530 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  value.  The.** [
2d540 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
2d550 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  p()] interface c
2d560 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f  an be used to co
2d570 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a  nstruct a new .*
2d580 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  * protected sqli
2d590 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61  te3_value from a
2d5a0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
2d5b0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
2d5c0 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
2d5d0 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
2d5e0 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
2d5f0 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
2d600 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
2d610 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72   held.  An inter
2d620 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
2d630 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
2d640 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2d650 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
2d660 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
2d670 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
2d680 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2d690 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
2d6a0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
2d6b0 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
2d6c0 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
2d6d0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
2d6e0 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
2d6f0 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
2d700 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
2d710 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
2d720 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
2d730 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
2d740 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
2d750 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
2d760 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
2d770 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
2d780 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
2d790 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
2d7a0 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
2d7b0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
2d7c0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
2d7d0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2d7e0 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
2d7f0 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
2d800 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
2d810 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
2d820 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
2d830 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
2d840 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
2d850 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
2d860 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
2d870 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
2d880 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
2d890 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
2d8a0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2d8b0 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
2d8c0 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
2d8d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2d8e0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2d8f0 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
2d900 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
2d910 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
2d920 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
2d930 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2d940 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2d950 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
2d960 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2d970 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
2d980 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
2d990 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2d9a0 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
2d9b0 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
2d9c0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2d9d0 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
2d9e0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
2d9f0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
2da00 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
2da10 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
2da20 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
2da30 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2da40 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
2da50 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
2da60 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
2da70 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
2da80 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2da90 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
2daa0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2dab0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 73 71  sqlite3_value sq
2dac0 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
2dad0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
2dae0 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
2daf0 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
2db00 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
2db10 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
2db20 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
2db30 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
2db40 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2db50 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
2db60 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
2db70 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
2db80 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
2db90 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
2dba0 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
2dbb0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2dbc0 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
2dbd0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2dbe0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
2dbf0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
2dc00 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
2dc10 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
2dc20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
2dc30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
2dc40 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
2dc50 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
2dc60 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2dc70 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
2dc80 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
2dc90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
2dca0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
2dcb0 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
2dcc0 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
2dcd0 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
2dce0 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
2dcf0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2dd00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2dd10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
2dd20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2dd30 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
2dd40 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
2dd50 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
2dd60 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
2dd70 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
2dd80 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
2dd90 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
2dda0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
2ddb0 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
2ddc0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
2ddd0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
2dde0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2ddf0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28  e3_stmt.**.** ^(
2de00 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  In the SQL state
2de10 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20  ment text input 
2de20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
2de30 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
2de40 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
2de50 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
2de60 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61  eplaced by a [pa
2de70 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61  rameter] that ma
2de80 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c  tches one of fol
2de90 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61  lowing.** templa
2dea0 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  tes:.**.** <ul>.
2deb0 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
2dec0 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
2ded0 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
2dee0 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
2def0 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
2df00 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74  * In the templat
2df10 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65  es above, NNN re
2df20 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65  presents an inte
2df30 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
2df40 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e  and VVV represen
2df50 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72  ts an alphanumer
2df60 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e  ic identifier.)^
2df70 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66    ^The values of
2df80 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
2df90 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
2dfa0 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
2dfb0 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
2dfc0 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
2dfd0 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
2dfe0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
2dff0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2e000 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
2e010 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
2e020 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
2e030 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2e040 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61  routines is alwa
2e050 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ys.** a pointer 
2e060 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2e070 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
2e080 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73  urned from.** [s
2e090 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2e0a0 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  2()] or its vari
2e0b0 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ants..**.** ^The
2e0c0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2e0d0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
2e0e0 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
2e0f0 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
2e100 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53   ^The leftmost S
2e110 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  QL parameter has
2e120 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
2e130 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20   ^When the same 
2e140 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72  named.** SQL par
2e150 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
2e160 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
2e170 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
2e180 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
2e190 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
2e1a0 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
2e1b0 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
2e1c0 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66  .** ^The index f
2e1d0 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
2e1e0 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
2e1f0 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
2e200 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2e210 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2e220 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
2e230 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a  d.  ^The index.*
2e240 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
2e250 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
2e260 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
2e270 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d  ^The NNN value m
2e280 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
2e290 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65   and the [sqlite
2e2a0 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61  3_limit()].** pa
2e2b0 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f  rameter [SQLITE_
2e2c0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
2e2d0 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20  UMBER] (default 
2e2e0 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a  value: 999)..**.
2e2f0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  ** ^The third ar
2e300 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
2e310 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
2e320 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
2e330 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
2e340 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2e350 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20  te3_bind_text() 
2e360 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2e370 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73  text16().** or s
2e380 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2e390 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
2e3a0 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f  nter then the fo
2e3b0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a  urth parameter.*
2e3c0 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64  * is ignored and
2e3d0 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20   the end result 
2e3e0 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73  is the same as s
2e3f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
2e400 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ()..**.** ^(In t
2e410 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
2e420 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
2e430 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
2e440 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
2e450 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2e460 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
2e470 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
2e480 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
2e490 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
2e4a0 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
2e4b0 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
2e4c0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
2e4d0 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74  ters.)^.** ^If t
2e4e0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2e4f0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2e500 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
2e510 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2e520 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  6().** is negati
2e530 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e  ve, then the len
2e540 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
2e550 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
2e560 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
2e570 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
2e580 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20   terminator..** 
2e590 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
2e5a0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2e5b0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
2e5c0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
2e5d0 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72  .** the behavior
2e5e0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2e5f0 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  * If a non-negat
2e600 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  ive fourth param
2e610 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64  eter is provided
2e620 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2e630 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _text().** or sq
2e640 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2e650 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  6() or sqlite3_b
2e660 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65  ind_text64() the
2e670 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65  n.** that parame
2e680 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20  ter must be the 
2e690 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77  byte offset.** w
2e6a0 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
2e6b0 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63  minator would oc
2e6c0 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65  cur assuming the
2e6d0 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c   string were NUL
2e6e0 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  .** terminated. 
2e6f0 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
2e700 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20  acters occur at 
2e710 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73  byte offsets les
2e720 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76  s than .** the v
2e730 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72  alue of the four
2e740 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65  th parameter the
2e750 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
2e760 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c  string value wil
2e770 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62  l.** contain emb
2e780 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65  edded NULs.  The
2e790 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
2e7a0 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67  ssions involving
2e7b0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68   strings.** with
2e7c0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
2e7d0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2e7e0 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
2e7f0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c  gument to the BL
2e800 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69  OB and string bi
2e810 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  nding interfaces
2e820 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63  .** is a destruc
2e830 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
2e840 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
2e850 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
2e860 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
2e870 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
2e880 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
2e890 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f   is called.** to
2e8a0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
2e8b0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65  BLOB or string e
2e8c0 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ven if the call 
2e8d0 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c  to bind API fail
2e8e0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  s..** ^If the fi
2e8f0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
2e900 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
2e910 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
2e920 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
2e930 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
2e940 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
2e950 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
2e960 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
2e970 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
2e980 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
2e990 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
2e9a0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
2e9b0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
2e9c0 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
2e9d0 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
2e9e0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
2e9f0 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
2ea00 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
2ea10 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
2ea20 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2ea30 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
2ea40 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61  .** ^The sixth a
2ea50 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2ea60 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2ea70 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a   must be one of.
2ea80 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ** [SQLITE_UTF8]
2ea90 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  , [SQLITE_UTF16]
2eaa0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
2eab0 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  E], or [SQLITE_U
2eac0 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70  TF16LE].** to sp
2ead0 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69  ecify the encodi
2eae0 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69  ng of the text i
2eaf0 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
2eb00 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68  meter.  If.** th
2eb10 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74  e sixth argument
2eb20 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2eb30 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74  _text64() is not
2eb40 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61   one of the.** a
2eb50 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68  llowed values sh
2eb60 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66  own above, or if
2eb70 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
2eb80 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a  ng is different.
2eb90 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f  ** from the enco
2eba0 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62  ding specified b
2ebb0 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61  y the sixth para
2ebc0 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
2ebd0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75  behavior.** is u
2ebe0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2ebf0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2ec00 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
2ec10 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
2ec20 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
2ec30 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
2ec40 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41  with zeroes.  ^A
2ec50 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
2ec60 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
2ec70 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
2ec80 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
2ec90 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
2eca0 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
2ecb0 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
2ecc0 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
2ecd0 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
2ece0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
2ecf0 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
2ed00 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
2ed10 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
2ed20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
2ed30 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
2ed40 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
2ed50 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65  utines..** ^A ne
2ed60 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
2ed70 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
2ed80 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
2ed90 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
2eda0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2edb0 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 53 2c 49  bind_pointer(S,I
2edc0 2c 50 2c 54 29 20 72 6f 75 74 69 6e 65 20 63 61  ,P,T) routine ca
2edd0 75 73 65 73 20 74 68 65 20 49 2d 74 68 20 70 61  uses the I-th pa
2ede0 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 5b 70  rameter in.** [p
2edf0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ee00 74 5d 20 53 20 74 6f 20 68 61 76 65 20 61 6e 20  t] S to have an 
2ee10 53 51 4c 20 76 61 6c 75 65 20 6f 66 20 4e 55 4c  SQL value of NUL
2ee20 4c 2c 20 62 75 74 20 74 6f 20 61 6c 73 6f 20 62  L, but to also b
2ee30 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  e.** associated 
2ee40 77 69 74 68 20 74 68 65 20 70 6f 69 6e 74 65 72  with the pointer
2ee50 20 50 20 6f 66 20 74 79 70 65 20 54 2e 0a 2a 2a   P of type T..**
2ee60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
2ee70 6e 64 5f 70 6f 69 6e 74 65 72 28 29 20 72 6f 75  nd_pointer() rou
2ee80 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
2ee90 20 74 6f 20 70 61 73 73 0a 2a 2a 20 68 6f 73 74   to pass.** host
2eea0 2d 6c 61 6e 67 75 61 67 65 20 70 6f 69 6e 74 65  -language pointe
2eeb0 72 73 20 69 6e 74 6f 20 5b 61 70 70 6c 69 63 61  rs into [applica
2eec0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2eed0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
2eee0 5e 41 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  ^A parameter tha
2eef0 74 20 69 73 20 69 6e 69 74 69 61 6c 69 7a 65 64  t is initialized
2ef00 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2ef10 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 29 5d 20  bind_pointer()] 
2ef20 61 70 70 65 61 72 73 0a 2a 2a 20 74 6f 20 62 65  appears.** to be
2ef30 20 61 6e 20 6f 72 64 69 6e 61 72 79 20 53 51 4c   an ordinary SQL
2ef40 20 4e 55 4c 4c 20 76 61 6c 75 65 20 74 6f 20 65   NULL value to e
2ef50 76 65 72 79 74 68 69 6e 67 20 6f 74 68 65 72 20  verything other 
2ef60 74 68 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  than.** [sqlite3
2ef70 5f 76 61 6c 75 65 5f 70 6f 69 6e 74 65 72 28 29  _value_pointer()
2ef80 5d 2e 20 20 54 68 65 20 54 20 70 61 72 61 6d 65  ].  The T parame
2ef90 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ter should be a 
2efa0 73 74 61 74 69 63 20 73 74 72 69 6e 67 2e 0a 2a  static string..*
2efb0 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20  *.** ^If any of 
2efc0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2efd0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  _*() routines ar
2efe0 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  e called with a 
2eff0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2f000 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  for the [prepare
2f010 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20  d statement] or 
2f020 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20  with a prepared 
2f030 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68  statement for wh
2f040 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ich.** [sqlite3_
2f050 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e  step()] has been
2f060 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63   called more rec
2f070 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69  ently than [sqli
2f080 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a  te3_reset()],.**
2f090 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77   then the call w
2f0a0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
2f0b0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20  TE_MISUSE].  If 
2f0c0 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  any sqlite3_bind
2f0d0 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69  _().** routine i
2f0e0 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70  s passed a [prep
2f0f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2f100 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69  that has been fi
2f110 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20  nalized, the.** 
2f120 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
2f130 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
2f140 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20   harmful..**.** 
2f150 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f  ^Bindings are no
2f160 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
2f170 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2f180 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e  )] routine..** ^
2f190 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  Unbound paramete
2f1a0 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  rs are interpret
2f1b0 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ed as NULL..**.*
2f1c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2f1d0 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72  ind_* routines r
2f1e0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
2f1f0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
2f200 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  an.** [error cod
2f210 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67  e] if anything g
2f220 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b  oes wrong..** ^[
2f230 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d  SQLITE_TOOBIG] m
2f240 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
2f250 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20   if the size of 
2f260 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
2f270 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69  .** exceeds limi
2f280 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73  ts imposed by [s
2f290 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
2f2a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2f2b0 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  TH]) or.** [SQLI
2f2c0 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a  TE_MAX_LENGTH]..
2f2d0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47  ** ^[SQLITE_RANG
2f2e0 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  E] is returned i
2f2f0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a  f the parameter.
2f300 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  ** index is out 
2f310 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c  of range.  ^[SQL
2f320 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
2f330 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
2f340 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  () fails..**.** 
2f350 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2f360 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2f370 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
2f380 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2f390 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
2f3a0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
2f3b0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2f3c0 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
2f3d0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73  ite3_bind_blob(s
2f3e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2f3f0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
2f400 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
2f410 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
2f420 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28  te3_bind_blob64(
2f430 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2f440 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
2f450 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
2f460 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2f470 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29           void(*)
2f480 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
2f490 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
2f4a0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2f4b0 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69   int, double);.i
2f4c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2f4d0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
2f4e0 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e  *, int, int);.in
2f4f0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
2f500 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
2f510 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
2f520 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c  _int64);.int sql
2f530 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
2f540 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2f550 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
2f560 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
2f570 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73  3_stmt*,int,cons
2f580 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64  t char*,int,void
2f590 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2f5a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2f5b0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
2f5c0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
2f5d0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
2f5e0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
2f5f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2f600 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
2f610 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68  *, int, const ch
2f620 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  ar*, sqlite3_uin
2f630 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20  t64,.           
2f640 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
2f650 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e  id(*)(void*), un
2f660 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f  signed char enco
2f670 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74  ding);.int sqlit
2f680 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
2f690 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2f6a0 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
2f6b0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2f6c0 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65  ite3_bind_pointe
2f6d0 72 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  r(sqlite3_stmt*,
2f6e0 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 63 6f 6e   int, void*, con
2f6f0 73 74 20 63 68 61 72 2a 29 3b 0a 69 6e 74 20 73  st char*);.int s
2f700 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
2f710 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
2f720 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b  t*, int, int n);
2f730 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2f740 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c  d_zeroblob64(sql
2f750 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2f760 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29   sqlite3_uint64)
2f770 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f780 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
2f790 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d   Parameters.** M
2f7a0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2f7b0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  tmt.**.** ^This 
2f7c0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
2f7d0 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
2f7e0 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
2f7f0 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
2f800 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2f810 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
2f820 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
2f830 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
2f840 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
2f850 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
2f860 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
2f870 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
2f880 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
2f890 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
2f8a0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2f8b0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
2f8c0 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
2f8d0 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
2f8e0 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
2f8f0 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75  ne actually retu
2f900 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66  rns the index of
2f910 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69   the largest (ri
2f920 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61  ghtmost).** para
2f930 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66  meter. For all f
2f940 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e  orms except ?NNN
2f950 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72  , this will corr
2f960 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a  espond to the.**
2f970 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75   number of uniqu
2f980 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49  e parameters.  I
2f990 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  f parameters of 
2f9a0 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72  the ?NNN form ar
2f9b0 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
2f9c0 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
2f9d0 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a  the list.)^.**.*
2f9e0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2f9f0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2fa00 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
2fa10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2fa20 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2fa30 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2fa40 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2fa50 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2fa60 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2fa70 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2fa80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2fa90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2faa0 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
2fab0 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45   Parameter.** ME
2fac0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2fad0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
2fae0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2faf0 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69  eter_name(P,N) i
2fb00 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2fb10 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
2fb20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61  the N-th [SQL pa
2fb30 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
2fb40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2fb50 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c  ent] P..** ^(SQL
2fb60 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
2fb70 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f  he form "?NNN" o
2fb80 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
2fb90 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
2fba0 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63  have a name whic
2fbb0 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
2fbc0 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
2fbd0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
2fbe0 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69  AAA".** respecti
2fbf0 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65  vely..** In othe
2fc00 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
2fc10 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
2fc20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a  or "@" or "?".**
2fc30 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
2fc40 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
2fc50 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65  .)^.** ^Paramete
2fc60 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
2fc70 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
2fc80 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
2fc90 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
2fca0 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20  nd are referred 
2fcb0 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22  to as "nameless"
2fcc0 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   or "anonymous p
2fcd0 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
2fce0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73  * ^The first hos
2fcf0 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
2fd00 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
2fd10 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ot 0..**.** ^If 
2fd20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f  the value N is o
2fd30 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
2fd40 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d  f the N-th param
2fd50 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
2fd60 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
2fd70 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68  s returned.  ^Th
2fd80 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2fd90 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
2fda0 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
2fdb0 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
2fdc0 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
2fdd0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
2fde0 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
2fdf0 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
2fe00 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20  repare16()],.** 
2fe10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2fe20 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b 73 71  16_v2()], or [sq
2fe30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2fe40 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v3()]..**.** See
2fe50 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2fe60 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2fe70 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2fe80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2fe90 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2fea0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2feb0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2fec0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ndex()]..*/.cons
2fed0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2fee0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2fef0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2ff00 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
2ff10 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
2ff20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
2ff30 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
2ff40 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2ff50 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2ff60 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
2ff70 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
2ff80 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
2ff90 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e  ame.  ^The.** in
2ffa0 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e  dex value return
2ffb0 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66  ed is suitable f
2ffc0 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65  or use as the se
2ffd0 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  cond.** paramete
2ffe0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  r to [sqlite3_bi
2fff0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
30000 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72  bind()].  ^A zer
30010 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  o.** is returned
30020 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20   if no matching 
30030 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75  parameter is fou
30040 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65  nd.  ^The parame
30050 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
30060 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
30070 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
30080 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
30090 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
300a0 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
300b0 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
300c0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
300d0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
300e0 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
300f0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
30100 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
30110 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
30120 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
30130 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
30140 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
30150 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
30160 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
30170 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
30180 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
30190 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73  _index(sqlite3_s
301a0 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  tmt*, const char
301b0 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a   *zName);../*.**
301c0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
301d0 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e   All Bindings On
301e0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
301f0 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ement.** METHOD:
30200 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
30210 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f  .** ^Contrary to
30220 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
30230 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
30240 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
30250 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
30260 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
30270 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
30280 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
30290 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73  atement]..** ^Us
302a0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
302b0 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
302c0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
302d0 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
302e0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
302f0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
30300 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30310 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
30320 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
30330 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t Set.** METHOD:
30340 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
30350 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
30360 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
30370 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
30380 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
30390 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
303a0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 49 66   statement]. ^If
303b0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
303c0 74 75 72 6e 73 20 30 2c 20 74 68 61 74 20 6d 65  turns 0, that me
303d0 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65  ans the .** [pre
303e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
303f0 20 72 65 74 75 72 6e 73 20 6e 6f 20 64 61 74 61   returns no data
30400 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
30410 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e   [UPDATE])..** ^
30420 48 6f 77 65 76 65 72 2c 20 6a 75 73 74 20 62 65  However, just be
30430 63 61 75 73 65 20 74 68 69 73 20 72 6f 75 74 69  cause this routi
30440 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73  ne returns a pos
30450 69 74 69 76 65 20 6e 75 6d 62 65 72 20 64 6f 65  itive number doe
30460 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74 68  s not.** mean th
30470 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 72  at one or more r
30480 6f 77 73 20 6f 66 20 64 61 74 61 20 77 69 6c 6c  ows of data will
30490 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   be returned.  ^
304a0 41 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  A SELECT stateme
304b0 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79  nt.** will alway
304c0 73 20 68 61 76 65 20 61 20 70 6f 73 69 74 69 76  s have a positiv
304d0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
304e0 5f 63 6f 75 6e 74 28 29 20 62 75 74 20 64 65 70  _count() but dep
304f0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a  ending on the.**
30500 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
30510 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68  nstraints and th
30520 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e 74 2c  e table content,
30530 20 69 74 20 6d 69 67 68 74 20 72 65 74 75 72 6e   it might return
30540 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20   no rows..**.** 
30550 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
30560 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
30570 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
30580 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
30590 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
305a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
305b0 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
305c0 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
305d0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
305e0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
305f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
30600 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
30610 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
30620 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
30630 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
30640 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
30650 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54  ] statement.  ^T
30660 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
30670 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
30680 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
30690 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
306a0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
306b0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
306c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
306d0 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
306e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
306f0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
30700 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
30710 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  .  ^The first pa
30720 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
30730 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30740 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
30750 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45  ements the [SELE
30760 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e  CT] statement. ^
30770 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
30780 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
30790 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e  olumn number.  ^
307a0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
307b0 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
307c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
307d0 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
307e0 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
307f0 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
30800 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30810 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
30820 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
30830 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
30840 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
30850 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
30860 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
30870 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
30880 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
30890 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
308a0 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
308b0 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
308c0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
308d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
308e0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
308f0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
30900 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
30910 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  .**.** ^If sqlit
30920 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
30930 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
30940 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
30950 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
30960 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
30970 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
30980 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
30990 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
309a0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
309b0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
309c0 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
309d0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
309e0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
309f0 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
30a00 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
30a10 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
30a20 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
30a30 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
30a40 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
30a50 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
30a60 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
30a70 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
30a80 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
30a90 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
30aa0 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f   the next..*/.co
30ab0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
30ac0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
30ad0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30ae0 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20   N);.const void 
30af0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
30b00 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
30b10 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
30b20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
30b30 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
30b40 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
30b50 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
30b60 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
30b70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
30b80 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
30b90 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
30ba0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
30bb0 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c  and.** table col
30bc0 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20  umn that is the 
30bd0 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74  origin of a part
30be0 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f  icular result co
30bf0 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45  lumn in.** [SELE
30c00 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  CT] statement..*
30c10 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
30c20 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
30c30 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
30c40 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
30c50 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
30c60 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74  F-8 or UTF-16 st
30c70 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74  ring.  ^The _dat
30c80 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
30c90 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
30ca0 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
30cb0 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
30cc0 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
30cd0 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
30ce0 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
30cf0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
30d00 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
30d10 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
30d20 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
30d30 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65  til the [prepare
30d40 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
30d50 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69  destroyed.** usi
30d60 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
30d70 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
30d80 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
30d90 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
30da0 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
30db0 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
30dc0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
30dd0 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
30de0 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
30df0 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
30e00 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
30e10 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
30e20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
30e30 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  ncoding..**.** ^
30e40 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
30e50 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
30e60 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
30e70 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
30e80 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
30e90 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
30ea0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
30eb0 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69  ument to these i
30ec0 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b  nterfaces is a [
30ed0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30ee0 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66  nt]..** ^These f
30ef0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
30f00 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
30f10 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  t the Nth result
30f20 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
30f30 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
30f40 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
30f50 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
30f60 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
30f70 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  * ^The left-most
30f80 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d   column is colum
30f90 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f  n 0 for these ro
30fa0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  utines..**.** ^I
30fb0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
30fc0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
30fd0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
30fe0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
30ff0 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
31000 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
31010 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
31020 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
31030 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
31040 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
31050 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
31060 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
31070 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
31080 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e  error.** occurs.
31090 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68    ^Otherwise, th
310a0 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  ey return the na
310b0 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
310c0 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
310d0 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e  le,.** or column
310e0 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
310f0 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  lt column was ex
31100 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
31110 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c  .** ^As with all
31120 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
31130 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20  Is, those whose 
31140 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22  names end with "
31150 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
31160 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
31170 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68  ings and the oth
31180 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
31190 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a  urn UTF-8..**.**
311a0 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65   ^These APIs are
311b0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
311c0 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
311d0 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
311e0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
311f0 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
31200 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
31210 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a  cessor symbol..*
31220 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
31230 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
31240 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
31250 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
31260 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
31270 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
31280 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
31290 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
312a0 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
312b0 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
312c0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  ned..**.** If tw
312d0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
312e0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
312f0 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  re.** [sqlite3_c
31300 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
31310 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74  ame | column met
31320 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
31330 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ].** for the sam
31340 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
31350 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c  ement] and resul
31360 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74  t column.** at t
31370 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
31380 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
31390 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
313a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
313b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
313c0 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
313d0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
313e0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
313f0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
31400 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
31410 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
31420 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
31430 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
31440 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
31450 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
31460 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
31470 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
31480 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
31490 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
314a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
314b0 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
314c0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
314d0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
314e0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
314f0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
31500 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
31510 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
31520 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
31530 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
31540 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
31550 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  3_stmt.**.** ^(T
31560 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
31570 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
31580 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
31590 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
315a0 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
315b0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
315c0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
315d0 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
315e0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
315f0 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
31600 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
31610 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
31620 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
31630 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
31640 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
31650 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
31660 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
31670 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
31680 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
31690 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
316a0 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
316b0 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
316c0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
316d0 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
316e0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
316f0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
31700 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
31710 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
31720 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
31730 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
31740 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
31750 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
31760 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
31770 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
31780 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
31790 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
317a0 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
317b0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
317c0 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
317d0 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
317e0 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
317f0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
31800 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
31810 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
31820 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
31830 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
31840 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
31850 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
31860 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
31870 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
31880 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
31890 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
318a0 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
318b0 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
318c0 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
318d0 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
318e0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
318f0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
31900 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
31910 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
31920 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
31930 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
31940 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
31950 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
31960 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
31970 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
31980 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
31990 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
319a0 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
319b0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
319c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
319d0 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  ltype(sqlite3_st
319e0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
319f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
31a00 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
31a10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
31a20 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
31a30 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e  REF: Evaluate An
31a40 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
31a50 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
31a60 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74  3_stmt.**.** Aft
31a70 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
31a80 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
31a90 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
31aa0 67 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73 71 6c  g any of.** [sql
31ab0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
31ac0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  )], [sqlite3_pre
31ad0 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c  pare_v3()], [sql
31ae0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
31af0 32 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  2()],.** or [sql
31b00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
31b10 33 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  3()] or one of t
31b20 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
31b30 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
31b40 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
31b50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
31b60 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74  6()], this funct
31b70 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63  ion.** must be c
31b80 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
31b90 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
31ba0 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
31bb0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
31bc0 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
31bd0 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69  vior of the sqli
31be0 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72  te3_step() inter
31bf0 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f  face depend.** o
31c00 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74  n whether the st
31c10 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70  atement was prep
31c20 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e  ared using the n
31c30 65 77 65 72 20 22 76 58 22 20 69 6e 74 65 72 66  ewer "vX" interf
31c40 61 63 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  aces.** [sqlite3
31c50 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20  _prepare_v3()], 
31c60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
31c70 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
31c80 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
31c90 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
31ca0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
31cb0 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
31cc0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
31cd0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
31ce0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
31cf0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
31d00 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
31d10 2a 20 6e 65 77 20 22 76 58 22 20 69 6e 74 65 72  * new "vX" inter
31d20 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
31d30 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
31d40 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
31d50 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
31d60 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
31d70 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
31d80 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
31d90 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
31da0 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
31db0 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
31dc0 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
31dd0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
31de0 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
31df0 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
31e00 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
31e10 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
31e20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
31e30 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
31e40 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
31e50 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
31e60 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
31e70 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
31e80 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
31e90 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
31ea0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
31eb0 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
31ec0 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
31ed0 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
31ee0 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
31ef0 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
31f00 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
31f10 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
31f20 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
31f30 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
31f40 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
31f50 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
31f60 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
31f70 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
31f80 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
31f90 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
31fa0 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
31fb0 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74  n an.** explicit
31fc0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
31fd0 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
31fe0 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
31ff0 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
32000 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
32010 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
32020 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
32030 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
32040 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
32050 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
32060 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
32070 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
32080 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
32090 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
320a0 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
320b0 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
320c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
320d0 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
320e0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
320f0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
32100 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
32110 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
32120 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
32130 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
32140 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
32150 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
32160 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
32170 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
32180 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
32190 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
321a0 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
321b0 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
321c0 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
321d0 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
321e0 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
321f0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
32200 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
32210 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
32220 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
32230 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
32240 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
32250 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
32260 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
32270 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
32280 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
32290 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
322a0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
322b0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
322c0 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
322d0 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
322e0 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
322f0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
32300 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
32310 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
32320 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
32330 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
32340 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
32350 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
32360 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
32370 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
32380 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
32390 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
323a0 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
323b0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
323c0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
323d0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
323e0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
323f0 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
32400 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
32410 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
32420 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
32430 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
32440 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
32450 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
32460 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
32470 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
32480 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
32490 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
324a0 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
324b0 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
324c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
324d0 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
324e0 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
324f0 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
32500 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
32510 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
32520 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
32530 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
32540 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
32550 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
32560 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
32570 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
32580 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
32590 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
325a0 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
325b0 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
325c0 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
325d0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
325e0 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
325f0 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
32600 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
32610 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  1, a call to.** 
32620 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
32630 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61  ] was required a
32640 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
32650 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
32660 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74  thing.** other t
32670 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
32680 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
32690 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
326a0 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
326b0 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
326c0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72   to reset the pr
326d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
326e0 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
326f0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75  te3_reset()] wou
32700 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ld result in an 
32710 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
32720 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73  return from.** s
32730 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
32740 42 75 74 20 61 66 74 65 72 20 5b 76 65 72 73 69  But after [versi
32750 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b 64  on 3.6.23.1] ([d
32760 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c  ateof:3.6.23.1],
32770 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
32780 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c  () began.** call
32790 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
327a0 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61  et()] automatica
327b0 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63  lly in this circ
327c0 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a  umstance rather.
327d0 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e  ** than returnin
327e0 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  g [SQLITE_MISUSE
327f0 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20  ].  This is not 
32800 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d  considered a com
32810 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72  patibility.** br
32820 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20  eak because any 
32830 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74  application that
32840 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61   ever receives a
32850 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  n SQLITE_MISUSE 
32860 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b  error.** is brok
32870 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e  en by definition
32880 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
32890 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63  MIT_AUTORESET] c
328a0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
328b0 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  on.** can be use
328c0 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65  d to restore the
328d0 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
328e0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79  ..**.** <b>Goofy
328f0 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
32900 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67  :</b> In the leg
32910 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
32920 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
32930 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20  ).** API always 
32940 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69  returns a generi
32950 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53  c error code, [S
32960 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f  QLITE_ERROR], fo
32970 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65  llowing any.** e
32980 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20  rror other than 
32990 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e  [SQLITE_BUSY] an
329a0 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  d [SQLITE_MISUSE
329b0 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c  ].  You must cal
329c0 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  l.** [sqlite3_re
329d0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
329e0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
329f0 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
32a00 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70  one of the.** sp
32a10 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
32a20 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72  des] that better
32a30 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
32a40 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69  rror..** We admi
32a50 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61  t that this is a
32a60 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20   goofy design.  
32a70 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20  The problem has 
32a80 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69  been fixed.** wi
32a90 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
32aa0 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70  rface.  If you p
32ab0 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f  repare all of yo
32ac0 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ur SQL statement
32ad0 73 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  s.** using [sqli
32ae0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
32af0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
32b00 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 6f  epare_v2()].** o
32b10 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
32b20 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 5b 73  re16_v2()] or [s
32b30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
32b40 5f 76 33 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v3()] instead.*
32b50 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
32b60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
32b70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
32b80 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
32b90 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
32ba0 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
32bb0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
32bc0 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
32bd0 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
32be0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
32bf0 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
32c00 58 22 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  X" interfaces is
32c10 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f   recommended..*/
32c20 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65  .int sqlite3_ste
32c30 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
32c40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32c50 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  F: Number of col
32c60 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74  umns in a result
32c70 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   set.** METHOD: 
32c80 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
32c90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
32ca0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e  data_count(P) in
32cb0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
32cc0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
32cd0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20  lumns in the.** 
32ce0 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
32cf0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
32d00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32d10 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20  ment] P..** ^If 
32d20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
32d30 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61  nt P does not ha
32d40 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79  ve results ready
32d50 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76   to return.** (v
32d60 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ia calls to the 
32d70 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
32d80 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f  int | sqlite3_co
32d90 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20  lumn_*()] of.** 
32da0 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e  interfaces) then
32db0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
32dc0 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30  unt(P) returns 0
32dd0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
32de0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
32df0 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74  routine also ret
32e00 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61  urns 0 if P is a
32e10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
32e20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
32e30 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
32e40 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
32e50 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
32e60 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
32e70 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
32e80 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  rned [SQLITE_DON
32e90 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  E].  ^The sqlite
32ea0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a  3_data_count(P).
32eb0 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e  ** will return n
32ec0 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69  on-zero if previ
32ed0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ous call to [sql
32ee0 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
32ef0 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54  turned.** [SQLIT
32f00 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69  E_ROW], except i
32f10 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68  n the case of th
32f20 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d  e [PRAGMA increm
32f30 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a  ental_vacuum].**
32f40 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73   where it always
32f50 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69   returns zero si
32f60 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66  nce each step of
32f70 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70   that multi-step
32f80 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72  .** pragma retur
32f90 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  ns 0 columns of 
32fa0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  data..**.** See 
32fb0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63  also: [sqlite3_c
32fc0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a  olumn_count()].*
32fd0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61  /.int sqlite3_da
32fe0 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  ta_count(sqlite3
32ff0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
33000 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33010 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61  Fundamental Data
33020 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  types.** KEYWORD
33030 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
33040 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c  *.** ^(Every val
33050 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
33060 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
33070 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
33080 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
33090 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
330a0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
330b0 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
330c0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
330d0 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
330e0 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
330f0 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
33100 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
33110 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
33120 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
33130 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
33140 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
33150 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
33160 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
33170 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
33180 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
33190 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
331a0 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
331b0 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
331c0 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
331d0 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
331e0 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
331f0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
33200 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
33210 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
33220 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
33230 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33240 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
33250 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
33260 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
33270 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
33280 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
33290 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
332a0 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
332b0 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
332c0 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
332d0 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
332e0 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
332f0 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
33300 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
33310 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
33320 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a  s From A Query.*
33330 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c  * KEYWORDS: {col
33340 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
33350 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ions}.** METHOD:
33360 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
33370 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72 79 3a 3c  .** <b>Summary:<
33380 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  /b>.** <blockquo
33390 74 65 3e 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  te><table border
333a0 3d 30 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 30  =0 cellpadding=0
333b0 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d 30 3e 0a   cellspacing=0>.
333c0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
333d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
333e0 62 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  b</b><td>&rarr;<
333f0 74 64 3e 42 4c 4f 42 20 72 65 73 75 6c 74 0a 2a  td>BLOB result.*
33400 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
33410 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
33420 6c 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  le</b><td>&rarr;
33430 3c 74 64 3e 52 45 41 4c 20 72 65 73 75 6c 74 0a  <td>REAL result.
33440 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
33450 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
33460 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
33470 64 3e 33 32 2d 62 69 74 20 49 4e 54 45 47 45 52  d>32-bit INTEGER
33480 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c   result.** <tr><
33490 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
334a0 6c 75 6d 6e 5f 69 6e 74 36 34 3c 2f 62 3e 3c 74  lumn_int64</b><t
334b0 64 3e 26 72 61 72 72 3b 3c 74 64 3e 36 34 2d 62  d>&rarr;<td>64-b
334c0 69 74 20 49 4e 54 45 47 45 52 20 72 65 73 75 6c  it INTEGER resul
334d0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  t.** <tr><td><b>
334e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
334f0 65 78 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  ext</b><td>&rarr
33500 3b 3c 74 64 3e 55 54 46 2d 38 20 54 45 58 54 20  ;<td>UTF-8 TEXT 
33510 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74  result.** <tr><t
33520 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
33530 75 6d 6e 5f 74 65 78 74 31 36 3c 2f 62 3e 3c 74  umn_text16</b><t
33540 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d  d>&rarr;<td>UTF-
33550 31 36 20 54 45 58 54 20 72 65 73 75 6c 74 0a 2a  16 TEXT result.*
33560 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
33570 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
33580 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  e</b><td>&rarr;<
33590 74 64 3e 54 68 65 20 72 65 73 75 6c 74 20 61 73  td>The result as
335a0 20 61 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   an .** [sqlite3
335b0 5f 76 61 6c 75 65 7c 75 6e 70 72 6f 74 65 63 74  _value|unprotect
335c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
335d0 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 3c 74 72  ] object..** <tr
335e0 3e 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26  ><td>&nbsp;<td>&
335f0 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 0a  nbsp;<td>&nbsp;.
33600 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
33610 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
33620 65 73 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  es</b><td>&rarr;
33630 3c 74 64 3e 53 69 7a 65 20 6f 66 20 61 20 42 4c  <td>Size of a BL
33640 4f 42 0a 2a 2a 20 6f 72 20 61 20 55 54 46 2d 38  OB.** or a UTF-8
33650 20 54 45 58 54 20 72 65 73 75 6c 74 20 69 6e 20   TEXT result in 
33660 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64  bytes.** <tr><td
33670 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ><b>sqlite3_colu
33680 6d 6e 5f 62 79 74 65 73 31 36 26 6e 62 73 70 3b  mn_bytes16&nbsp;
33690 26 6e 62 73 70 3b 3c 2f 62 3e 0a 2a 2a 20 3c 74  &nbsp;</b>.** <t
336a0 64 3e 26 72 61 72 72 3b 26 6e 62 73 70 3b 26 6e  d>&rarr;&nbsp;&n
336b0 62 73 70 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20  bsp;<td>Size of 
336c0 55 54 46 2d 31 36 0a 2a 2a 20 54 45 58 54 20 69  UTF-16.** TEXT i
336d0 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c  n bytes.** <tr><
336e0 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
336f0 6c 75 6d 6e 5f 74 79 70 65 3c 2f 62 3e 3c 74 64  lumn_type</b><td
33700 3e 26 72 61 72 72 3b 3c 74 64 3e 44 65 66 61 75  >&rarr;<td>Defau
33710 6c 74 0a 2a 2a 20 64 61 74 61 74 79 70 65 20 6f  lt.** datatype o
33720 66 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20  f the result.** 
33730 3c 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f 63 6b 71  </table></blockq
33740 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 44  uote>.**.** <b>D
33750 65 74 61 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a 0a 2a  etails:</b>.**.*
33760 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
33770 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
33780 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e  tion about a sin
33790 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
337a0 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73  e current.** res
337b0 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
337c0 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63  ry.  ^In every c
337d0 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72  ase the first ar
337e0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
337f0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70  ter.** to the [p
33800 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33810 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67  t] that is being
33820 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20   evaluated (the 
33830 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a  [sqlite3_stmt*].
33840 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75  ** that was retu
33850 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  rned from [sqlit
33860 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
33870 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76   or one of its v
33880 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20  ariants).** and 
33890 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
338a0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
338b0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66   of the column f
338c0 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61  or which informa
338d0 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
338e0 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65  e returned. ^The
338f0 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
33900 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
33910 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78  et has the index
33920 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62   0..** ^The numb
33930 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
33940 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20   the result can 
33950 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
33960 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
33970 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e  column_count()].
33980 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
33990 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
339a0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70   not currently p
339b0 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20  oint to a valid 
339c0 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a  row, or if the.*
339d0 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69  * column index i
339e0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
339f0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e  the result is un
33a00 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73  defined..** Thes
33a10 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f  e routines may o
33a20 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
33a30 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  en the most rece
33a40 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
33a50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
33a60 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  as returned [SQL
33a70 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69  ITE_ROW] and nei
33a80 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
33a90 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73  _reset()] nor [s
33aa0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
33ab0 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  )] have been cal
33ac0 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79  led subsequently
33ad0 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74  ..** If any of t
33ae0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
33af0 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  e called after [
33b00 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
33b10 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
33b20 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  finalize()] or a
33b30 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
33b40 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
33b50 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20  ed.** something 
33b60 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
33b70 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73  TE_ROW], the res
33b80 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
33b90 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  ed..** If [sqlit
33ba0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
33bb0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
33bc0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
33bd0 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63  lize()].** are c
33be0 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66  alled from a dif
33bf0 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68  ferent thread wh
33c00 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  ile any of these
33c10 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
33c20 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74   pending, then t
33c30 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
33c40 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
33c50 54 68 65 20 66 69 72 73 74 20 73 69 78 20 69 6e  The first six in
33c60 74 65 72 66 61 63 65 73 20 28 5f 62 6c 6f 62 2c  terfaces (_blob,
33c70 20 5f 64 6f 75 62 6c 65 2c 20 5f 69 6e 74 2c 20   _double, _int, 
33c80 5f 69 6e 74 36 34 2c 20 5f 74 65 78 74 2c 20 61  _int64, _text, a
33c90 6e 64 20 5f 74 65 78 74 31 36 29 0a 2a 2a 20 65  nd _text16).** e
33ca0 61 63 68 20 72 65 74 75 72 6e 20 74 68 65 20 76  ach return the v
33cb0 61 6c 75 65 20 6f 66 20 61 20 72 65 73 75 6c 74  alue of a result
33cc0 20 63 6f 6c 75 6d 6e 20 69 6e 20 61 20 73 70 65   column in a spe
33cd0 63 69 66 69 63 20 64 61 74 61 20 66 6f 72 6d 61  cific data forma
33ce0 74 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 72 65  t.  If.** the re
33cf0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  sult column is n
33d00 6f 74 20 69 6e 69 74 69 61 6c 6c 79 20 69 6e 20  ot initially in 
33d10 74 68 65 20 72 65 71 75 65 73 74 65 64 20 66 6f  the requested fo
33d20 72 6d 61 74 20 28 66 6f 72 20 65 78 61 6d 70 6c  rmat (for exampl
33d30 65 2c 0a 2a 2a 20 69 66 20 74 68 65 20 71 75 65  e,.** if the que
33d40 72 79 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ry returns an in
33d50 74 65 67 65 72 20 62 75 74 20 74 68 65 20 73 71  teger but the sq
33d60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
33d70 74 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  t() interface.**
33d80 20 69 73 20 75 73 65 64 20 74 6f 20 65 78 74 72   is used to extr
33d90 61 63 74 20 74 68 65 20 76 61 6c 75 65 29 20 74  act the value) t
33da0 68 65 6e 20 61 6e 20 61 75 74 6f 6d 61 74 69 63  hen an automatic
33db0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
33dc0 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a   is performed..*
33dd0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
33de0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
33df0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
33e00 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
33e10 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
33e20 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
33e30 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
33e40 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
33e50 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65  lt column.  ^The
33e60 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
33e70 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
33e80 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
33e90 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
33ea0 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
33eb0 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
33ec0 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 0a 2a  [SQLITE_NULL]..*
33ed0 2a 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  * The return val
33ee0 75 65 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  ue of sqlite3_co
33ef0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 63 61 6e 20  lumn_type() can 
33f00 62 65 20 75 73 65 64 20 74 6f 20 64 65 63 69 64  be used to decid
33f10 65 20 77 68 69 63 68 0a 2a 2a 20 6f 66 20 74 68  e which.** of th
33f20 65 20 66 69 72 73 74 20 73 69 78 20 69 6e 74 65  e first six inte
33f30 72 66 61 63 65 20 73 68 6f 75 6c 64 20 62 65 20  rface should be 
33f40 75 73 65 64 20 74 6f 20 65 78 74 72 61 63 74 20  used to extract 
33f50 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  the column value
33f60 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72  ..** The value r
33f70 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
33f80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
33f90 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
33fa0 66 75 6c 20 69 66 20 6e 6f 0a 2a 2a 20 61 75 74  ful if no.** aut
33fb0 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e 76  omatic type conv
33fc0 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
33fd0 75 72 72 65 64 20 66 6f 72 20 74 68 65 20 76 61  urred for the va
33fe0 6c 75 65 20 69 6e 20 71 75 65 73 74 69 6f 6e 2e  lue in question.
33ff0 20 20 0a 2a 2a 20 41 66 74 65 72 20 61 20 74 79    .** After a ty
34000 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 20 74  pe conversion, t
34010 68 65 20 72 65 73 75 6c 74 20 6f 66 20 63 61 6c  he result of cal
34020 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ling sqlite3_col
34030 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 69 73  umn_type().** is
34040 20 75 6e 64 65 66 69 6e 65 64 2c 20 74 68 6f 75   undefined, thou
34050 67 68 20 68 61 72 6d 6c 65 73 73 2e 20 20 46 75  gh harmless.  Fu
34060 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
34070 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
34080 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
34090 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
340a0 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
340b0 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
340c0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
340d0 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20  * If the result 
340e0 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 61 20 54  is a BLOB or a T
340f0 45 58 54 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  EXT string, then
34100 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
34110 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 6f  umn_bytes().** o
34120 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
34130 5f 62 79 74 65 73 31 36 28 29 20 69 6e 74 65 72  _bytes16() inter
34140 66 61 63 65 73 20 63 61 6e 20 62 65 20 75 73 65  faces can be use
34150 64 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  d to determine t
34160 68 65 20 73 69 7a 65 0a 2a 2a 20 6f 66 20 74 68  he size.** of th
34170 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
34180 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  g..**.** ^If the
34190 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
341a0 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e  B or UTF-8 strin
341b0 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
341c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
341d0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
341e0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
341f0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
34200 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
34210 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
34220 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73  lt is a UTF-16 s
34230 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
34240 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
34250 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
34260 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
34270 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  -8 and then retu
34280 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
34290 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
342a0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
342b0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
342c0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
342d0 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a  n_bytes() uses.*
342e0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
342f0 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
34300 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
34310 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61  a UTF-8 string a
34320 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
34330 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
34340 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
34350 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
34360 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
34370 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
34380 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73  _bytes() returns
34390 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   zero..**.** ^If
343a0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
343b0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20   BLOB or UTF-16 
343c0 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
343d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
343e0 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74  ytes16().** rout
343f0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
34400 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
34410 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
34420 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
34430 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
34440 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65  TF-8 string, the
34450 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
34460 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65  _bytes16() conve
34470 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
34480 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20  g to UTF-16 and 
34490 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
344a0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
344b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
344c0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
344d0 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
344e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
344f0 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  16() uses.** [sq
34500 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
34510 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
34520 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
34530 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72  -16 string and r
34540 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
34550 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
34560 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
34570 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
34580 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
34590 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
345a0 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a  es16() returns z
345b0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ero..**.** ^The 
345c0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
345d0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
345e0 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
345f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
34600 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64  umn_bytes16()] d
34610 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68  o not include th
34620 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
34630 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  rs at the end.**
34640 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
34650 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74   ^For clarity: t
34660 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
34670 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
34680 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
34690 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
346a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
346b0 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20   are the number 
346c0 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
346d0 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74  he string, not t
346e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
346f0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
34700 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  Strings returned
34710 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
34720 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71  mn_text() and sq
34730 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
34740 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65  t16(),.** even e
34750 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72  mpty strings, ar
34760 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  e always zero-te
34770 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
34780 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
34790 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
347a0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
347b0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
347c0 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  B is a NULL poin
347d0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61  ter..**.** <b>Wa
347e0 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20  rning:</b> ^The 
347f0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
34800 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
34810 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61  mn_value()] is a
34820 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
34830 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
34840 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d   object.  In a m
34850 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e 76  ultithreaded env
34860 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20  ironment,.** an 
34870 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
34880 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
34890 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
348a0 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a  d safely with.**
348b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
348c0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
348d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
348e0 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
348f0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
34900 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
34910 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
34920 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
34930 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
34940 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
34950 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
34960 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
34970 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
34980 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
34990 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
349a0 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
349b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
349c0 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76  es()], the behav
349d0 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ior is not threa
349e0 64 73 61 66 65 2e 0a 2a 2a 20 48 65 6e 63 65 2c  dsafe..** Hence,
349f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
34a00 75 6d 6e 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  umn_value() inte
34a10 72 66 61 63 65 0a 2a 2a 20 69 73 20 6e 6f 72 6d  rface.** is norm
34a20 61 6c 6c 79 20 6f 6e 6c 79 20 75 73 65 66 75 6c  ally only useful
34a30 20 77 69 74 68 69 6e 20 74 68 65 20 69 6d 70 6c   within the impl
34a40 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 0a 2a  ementation of .*
34a50 2a 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  * [application-d
34a60 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
34a70 69 6f 6e 73 5d 20 6f 72 20 5b 76 69 72 74 75 61  ions] or [virtua
34a80 6c 20 74 61 62 6c 65 73 5d 2c 20 6e 6f 74 20 77  l tables], not w
34a90 69 74 68 69 6e 0a 2a 2a 20 74 6f 70 2d 6c 65 76  ithin.** top-lev
34aa0 65 6c 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  el application c
34ab0 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ode..**.** The t
34ac0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
34ad0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e  y attempt to con
34ae0 76 65 72 74 20 74 68 65 20 64 61 74 61 74 79 70  vert the datatyp
34af0 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
34b00 0a 2a 2a 20 5e 46 6f 72 20 65 78 61 6d 70 6c 65  .** ^For example
34b10 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
34b20 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
34b30 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
34b40 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
34b50 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
34b60 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
34b70 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
34b80 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20  ally to perform 
34b90 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  the.** conversio
34ba0 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  n automatically.
34bb0 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e    ^(The followin
34bc0 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
34bd0 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a  the conversions.
34be0 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c  ** that are appl
34bf0 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
34c00 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
34c10 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
34c20 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
34c30 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
34c40 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
34c50 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
34c60 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
34c70 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
34c80 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
34c90 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
34ca0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
34cb0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
34cc0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
34cd0 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
34ce0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
34cf0 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
34d00 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
34d10 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
34d20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
34d30 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73  BLOB    <td> Res
34d40 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
34d50 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
34d60 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
34d70 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
34d80 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
34d90 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
34da0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
34db0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
34dc0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
34dd0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
34de0 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
34df0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
34e00 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
34e10 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54  me as INTEGER->T
34e20 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
34e30 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e   FLOAT   <td> IN
34e40 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
34e50 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
34e60 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
34e70 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
34e80 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
34e90 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
34ea0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
34eb0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
34ec0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43   BLOB    <td> [C
34ed0 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20  AST] to BLOB.** 
34ee0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
34ef0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
34f00 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
34f10 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
34f20 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
34f30 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
34f40 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a   [CAST] to REAL.
34f50 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
34f60 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  T    <td>   BLOB
34f70 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e      <td> No chan
34f80 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ge.** <tr><td>  
34f90 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54  BLOB    <td> INT
34fa0 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
34fb0 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
34fc0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
34fd0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
34fe0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
34ff0 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64   REAL.** <tr><td
35000 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
35010 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
35020 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
35030 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
35040 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
35050 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
35060 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
35070 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
35080 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
35090 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
350a0 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
350b0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
350c0 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
350d0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
350e0 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
350f0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
35100 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
35110 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
35120 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
35130 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
35140 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
35150 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
35160 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
35170 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
35180 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
35190 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
351a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
351b0 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
351c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
351d0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
351e0 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
351f0 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
35200 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
35210 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
35220 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
35230 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
35240 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
35250 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
35260 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
35270 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
35280 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
35290 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
352a0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
352b0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
352c0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
352d0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
352e0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
352f0 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
35300 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
35310 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
35320 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
35330 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
35340 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
35350 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
35360 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
35370 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
35380 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f   </ul>.**.** ^Co
35390 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
353a0 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
353b0 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
353c0 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
353d0 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
353e0 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
353f0 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
35400 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
35410 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
35420 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
35430 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
35440 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20  references will 
35450 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
35460 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
35470 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
35480 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
35490 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
354a0 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
354b0 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
354c0 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
354d0 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
354e0 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
354f0 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
35500 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
35510 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  est policy is to
35520 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
35530 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
35540 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
35550 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
35560 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
35570 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
35580 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
35590 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
355a0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
355b0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
355c0 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
355d0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
355e0 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
355f0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
35600 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
35610 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
35620 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
35630 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
35640 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
35650 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
35660 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
35670 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
35680 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
35690 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
356a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
356b0 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
356c0 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
356d0 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
356e0 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
356f0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
35700 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
35710 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
35720 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
35730 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
35740 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
35750 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
35760 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
35770 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
35780 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
35790 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
357a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
357b0 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
357c0 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
357d0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
357e0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
357f0 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
35800 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
35810 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tes()..**.** ^Th
35820 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
35830 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
35840 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
35850 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
35860 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
35870 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
35880 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
35890 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
358a0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
358b0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
358c0 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d   called.  ^The m
358d0 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
358e0 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
358f0 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
35900 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
35910 61 6c 6c 79 2e 20 20 44 6f 20 6e 6f 74 20 70 61  ally.  Do not pa
35920 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20  ss the pointers 
35930 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
35940 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
35950 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
35960 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
35970 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20  ], etc. into.** 
35980 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
35990 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d  ..**.** ^(If a m
359a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
359b0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
359c0 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74  ring the evaluat
359d0 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ion of any.** of
359e0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
359f0 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65   a default value
35a00 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
35a10 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
35a20 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68  .** is either th
35a30 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65  e integer 0, the
35a40 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
35a50 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61  number 0.0, or a
35a60 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
35a70 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61  .  Subsequent ca
35a80 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
35a90 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20  errcode()] will 
35aa0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
35ab0 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63  E_NOMEM].)^.*/.c
35ac0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
35ad0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73  e3_column_blob(s
35ae0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
35af0 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20  t iCol);.double 
35b00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
35b10 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
35b20 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
35b30 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
35b40 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
35b50 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
35b60 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
35b70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
35b80 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
35b90 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
35ba0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
35bb0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
35bc0 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
35bd0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
35be0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
35bf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
35c00 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
35c10 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
35c20 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
35c30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
35c40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
35c50 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
35c60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
35c70 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
35c80 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
35c90 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
35ca0 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
35cb0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
35cc0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35cd0 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
35ce0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
35cf0 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ol);../*.** CAPI
35d00 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20  3REF: Destroy A 
35d10 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
35d20 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53  nt Object.** DES
35d30 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
35d40 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
35d50 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
35d60 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
35d70 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
35d80 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
35d90 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
35da0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
35db0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68  evaluation of th
35dc0 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f  e statement enco
35dd0 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72  untered no error
35de0 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73  s.** or if the s
35df0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65  tatement is neve
35e00 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64  r been evaluated
35e10 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66  , then sqlite3_f
35e20 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e  inalize() return
35e30 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20  s.** SQLITE_OK. 
35e40 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
35e50 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
35e60 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66  of statement S f
35e70 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73  ailed, then.** s
35e80 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
35e90 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61  S) returns the a
35ea0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
35eb0 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  r code] or.** [e
35ec0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
35ed0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
35ee0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
35ef0 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  (S) routine can 
35f00 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
35f10 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a   point during.**
35f20 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20   the life cycle 
35f30 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
35f40 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65  tement] S:.** be
35f50 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53  fore statement S
35f60 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74   is ever evaluat
35f70 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65  ed, after.** one
35f80 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74   or more calls t
35f90 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
35fa0 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e  ()], or after an
35fb0 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71  y call.** to [sq
35fc0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
35fd0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
35fe0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73  her or not the s
35ff0 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20  tatement has.** 
36000 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
36010 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f  ion..**.** ^Invo
36020 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e  king sqlite3_fin
36030 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c  alize() on a NUL
36040 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68  L pointer is a h
36050 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
36060 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
36070 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69  tion must finali
36080 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72  ze every [prepar
36090 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
360a0 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a   order to avoid.
360b0 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b  ** resource leak
360c0 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65  s.  It is a grie
360d0 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74  vous error for t
360e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
360f0 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20  o try to use.** 
36100 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
36110 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
36120 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
36130 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20  .  Any use of a 
36140 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
36150 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
36160 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
36170 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20  d can result in 
36180 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a  undefined and.**
36190 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
361a0 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65  avior such as se
361b0 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70  gfaults and heap
361c0 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
361d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
361e0 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
361f0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
36200 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
36210 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
36220 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
36230 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
36240 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  _stmt.**.** The 
36250 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
36260 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
36270 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
36280 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36290 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
362a0 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
362b0 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
362c0 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
362d0 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61  .** ^Any SQL sta
362e0 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
362f0 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
36300 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
36310 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
36320 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
36330 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
36340 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
36350 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
36360 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
36370 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
36380 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
36390 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ngs..**.** ^The 
363a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
363b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
363c0 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
363d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
363e0 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65  * back to the be
363f0 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
36400 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  rogram..**.** ^I
36410 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
36420 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
36430 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
36440 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
36450 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65   statement] S re
36460 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
36470 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OW] or [SQLITE_D
36480 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b  ONE],.** or if [
36490 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
364a0 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
364b0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
364c0 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c   S,.** then [sql
364d0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
364e0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
364f0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  K]..**.** ^If th
36500 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
36510 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
36520 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
36530 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
36540 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
36550 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
36560 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  en.** [sqlite3_r
36570 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
36580 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
36590 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
365a0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
365b0 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
365c0 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63  rface does not c
365d0 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73  hange the values
365e0 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69  .** of any [sqli
365f0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
36600 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b  ndings] on the [
36610 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
36620 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nt] S..*/.int sq
36630 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69  lite3_reset(sqli
36640 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
36650 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36660 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64  F: Create Or Red
36670 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69  efine SQL Functi
36680 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
36690 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   {function creat
366a0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a  ion routines}.**
366b0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
366c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
366d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a  SQL function}.**
366e0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
366f0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
36700 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  SQL functions}.*
36710 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
36720 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  3.**.** ^These f
36730 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63  unctions (collec
36740 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  tively known as 
36750 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  "function creati
36760 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a  on routines").**
36770 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
36780 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
36790 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20  r aggregates or 
367a0 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20  to redefine the 
367b0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65  behavior.** of e
367c0 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
367d0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
367e0 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64  tes.  The only d
367f0 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65  ifferences betwe
36800 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74  en.** these rout
36810 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78  ines are the tex
36820 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63  t encoding expec
36830 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73  ted for.** the s
36840 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
36850 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  (the name of the
36860 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20   function being 
36870 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20  created).** and 
36880 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20  the presence or 
36890 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73  absence of a des
368a0 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
368b0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c   for.** the appl
368c0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
368d0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
368e0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
368f0 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73   is the [databas
36900 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
36910 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a   which the SQL.*
36920 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f  * function is to
36930 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20   be added.  ^If 
36940 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
36950 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
36960 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
36970 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70  nnection then ap
36980 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
36990 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
369a0 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a  must be added.**
369b0 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
369c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70  e connection sep
369d0 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  arately..**.** ^
369e0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
369f0 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
36a00 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
36a10 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74  tion to be creat
36a20 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e  ed or.** redefin
36a30 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68  ed.  ^The length
36a40 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20   of the name is 
36a50 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62  limited to 255 b
36a60 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a  ytes in a UTF-8.
36a70 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ** representatio
36a80 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20  n, exclusive of 
36a90 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
36aa0 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74  tor.  ^Note that
36ab0 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e   the name.** len
36ac0 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20  gth limit is in 
36ad0 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74  UTF-8 bytes, not
36ae0 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20   characters nor 
36af0 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a  UTF-16 bytes.  .
36b00 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20  ** ^Any attempt 
36b10 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63  to create a func
36b20 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67  tion with a long
36b30 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  er name.** will 
36b40 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54  result in [SQLIT
36b50 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20  E_MISUSE] being 
36b60 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
36b70 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
36b80 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69  eter (nArg).** i
36b90 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
36ba0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74  arguments that t
36bb0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
36bc0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
36bd0 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20  takes. ^If this 
36be0 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c  parameter is -1,
36bf0 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75   then the SQL fu
36c00 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
36c10 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20  regate may take 
36c20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  any number of ar
36c30 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20  guments between 
36c40 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a  0 and the limit.
36c50 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74  ** set by [sqlit
36c60 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
36c70 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
36c80 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20  _ARG]).  If the 
36c90 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
36ca0 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  er is less than 
36cb0 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  -1 or greater th
36cc0 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20  an 127 then the 
36cd0 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75  behavior is.** u
36ce0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
36cf0 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
36d00 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c  meter, eTextRep,
36d10 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a   specifies what.
36d20 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
36d30 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  | text encoding]
36d40 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69   this SQL functi
36d50 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a  on prefers for.*
36d60 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73  * its parameters
36d70 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
36d80 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68  on should set th
36d90 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  is parameter to.
36da0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ** [SQLITE_UTF16
36db0 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74  LE] if the funct
36dc0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
36dd0 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b  on invokes .** [
36de0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
36df0 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20  xt16le()] on an 
36e00 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54  input, or [SQLIT
36e10 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74 68  E_UTF16BE] if th
36e20 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
36e30 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c  ion invokes [sql
36e40 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
36e50 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70  6be()] on an inp
36e60 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  ut, or.** [SQLIT
36e70 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c  E_UTF16] if [sql
36e80 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
36e90 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72  6()] is used, or
36ea0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a   [SQLITE_UTF8].*
36eb0 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54  * otherwise.  ^T
36ec0 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
36ed0 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69  tion may be regi
36ee0 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20  stered multiple 
36ef0 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64  times using.** d
36f00 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 72 72  ifferent preferr
36f10 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
36f20 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  s, with differen
36f30 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
36f40 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e  s for.** each en
36f50 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e  coding..** ^When
36f60 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
36f70 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
36f80 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61   same function a
36f90 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51  re available, SQ
36fa0 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63  Lite.** will pic
36fb0 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69  k the one that i
36fc0 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73  nvolves the leas
36fd0 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
36fe0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
36ff0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
37000 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74  arameter may opt
37010 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20  ionally be ORed 
37020 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54  with [SQLITE_DET
37030 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74  ERMINISTIC].** t
37040 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68  o signal that th
37050 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  e function will 
37060 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68  always return th
37070 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69  e same result gi
37080 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ven.** the same 
37090 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61 20  inputs within a 
370a0 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
370b0 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20  ment.  Most SQL 
370c0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a  functions are.**
370d0 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20   deterministic. 
370e0 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72   The built-in [r
370f0 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e  andom()] SQL fun
37100 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d  ction is an exam
37110 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63  ple of a.** func
37120 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74  tion that is not
37130 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20   deterministic. 
37140 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65 72   The SQLite quer
37150 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c  y planner is abl
37160 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20  e to.** perform 
37170 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d  additional optim
37180 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65  izations on dete
37190 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69  rministic functi
371a0 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f  ons, so use.** o
371b0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45  f the [SQLITE_DE
371c0 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61  TERMINISTIC] fla
371d0 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  g is recommended
371e0 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e   where possible.
371f0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66  .**.** ^(The fif
37200 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
37210 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69  an arbitrary poi
37220 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65  nter.  The imple
37230 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
37240 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  .** function can
37250 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20   gain access to 
37260 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69  this pointer usi
37270 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ng [sqlite3_user
37280 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a  _data()].)^.**.*
37290 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65  * ^The sixth, se
372a0 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68  venth and eighth
372b0 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75   parameters, xFu
372c0 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46  nc, xStep and xF
372d0 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69  inal, are.** poi
372e0 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75  nters to C-langu
372f0 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  age functions th
37300 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
37310 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
37320 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e  .** aggregate. ^
37330 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  A scalar SQL fun
37340 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
37350 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
37360 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a   of the xFunc.**
37370 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20   callback only; 
37380 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75  NULL pointers mu
37390 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
373a0 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46  the xStep and xF
373b0 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65  inal.** paramete
373c0 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74  rs. ^An aggregat
373d0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
373e0 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
373f0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74  mentation of xSt
37400 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c  ep.** and xFinal
37410 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   and NULL pointe
37420 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  r must be passed
37430 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20   for xFunc. ^To 
37440 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69  delete an existi
37450 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  ng.** SQL functi
37460 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
37470 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74   pass NULL point
37480 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ers for all thre
37490 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61  e function.** ca
374a0 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e  llbacks..**.** ^
374b0 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61  (If the ninth pa
374c0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
374d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
374e0 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e  on_v2() is not N
374f0 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  ULL,.** then it 
37500 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f  is destructor fo
37510 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
37520 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20  n data pointer. 
37530 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74  .** The destruct
37540 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  or is invoked wh
37550 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
37560 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68  is deleted, eith
37570 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f  er by being.** o
37580 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65  verloaded or whe
37590 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
375a0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
375b0 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74  .)^.** ^The dest
375c0 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69  ructor is also i
375d0 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61  nvoked if the ca
375e0 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
375f0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
37600 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20  _v2() fails..** 
37610 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75  ^When the destru
37620 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ctor callback of
37630 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d   the tenth param
37640 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c  eter is invoked,
37650 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64   it.** is passed
37660 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
37670 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f  nt which is a co
37680 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  py of the applic
37690 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70  ation data .** p
376a0 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73  ointer which was
376b0 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d   the fifth param
376c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
376d0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
376e0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  v2()..**.** ^It 
376f0 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
37700 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c  register multipl
37710 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
37720 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
37730 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20   functions with 
37740 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
37750 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69  t with either di
37760 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20  ffering numbers 
37770 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  of.** arguments 
37780 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65  or differing pre
37790 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
377a0 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20  dings.  ^SQLite 
377b0 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20  will use.** the 
377c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74  implementation t
377d0 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  hat most closely
377e0 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
377f0 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
37800 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
37810 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74   used.  ^A funct
37820 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
37830 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65  on with a non-ne
37840 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70  gative.** nArg p
37850 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65  arameter is a be
37860 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  tter match than 
37870 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  a function imple
37880 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a  mentation with.*
37890 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72  * a negative nAr
378a0 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  g.  ^A function 
378b0 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72  where the prefer
378c0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
378d0 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65  g.** matches the
378e0 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69   database encodi
378f0 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a  ng is a better.*
37900 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  * match than a f
37910 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
37920 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  e encoding is di
37930 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41  fferent.  .** ^A
37940 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
37950 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
37960 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65  ference is betwe
37970 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55  en UTF16le and U
37980 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63  TF16be.** is a c
37990 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e  loser match than
379a0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
379b0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
379c0 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20  ifference is.** 
379d0 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64  between UTF8 and
379e0 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42   UTF16..**.** ^B
379f0 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
37a00 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61  s may be overloa
37a10 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69  ded by new appli
37a20 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
37a30 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  unctions..**.** 
37a40 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ^An application-
37a50 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
37a60 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
37a70 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53   call other.** S
37a80 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
37a90 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68  .  However, such
37aa0 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a   calls must not.
37ab0 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ** close the dat
37ac0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37ad0 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72   nor finalize or
37ae0 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
37af0 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
37b00 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75   in which the fu
37b10 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
37b20 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  g..*/.int sqlite
37b30 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
37b40 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
37b50 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
37b60 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
37b70 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
37b80 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
37b90 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
37ba0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
37bb0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
37bc0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
37bd0 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
37be0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
37bf0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
37c00 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
37c10 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
37c20 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
37c30 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
37c40 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71  function16(.  sq
37c50 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
37c60 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69  st void *zFuncti
37c70 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
37c80 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
37c90 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
37ca0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
37cb0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
37cc0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
37cd0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
37ce0 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
37cf0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
37d00 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
37d10 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
37d20 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37d30 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
37d40 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
37d50 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  n_v2(.  sqlite3 
37d60 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
37d70 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
37d80 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
37d90 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
37da0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
37db0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
37dc0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
37dd0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
37de0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
37df0 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
37e00 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
37e10 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
37e20 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
37e30 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20  e3_context*),.  
37e40 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
37e50 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
37e60 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
37e70 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20  Encodings.**.** 
37e80 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64  These constant d
37e90 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f  efine integer co
37ea0 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65  des that represe
37eb0 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a  nt the various.*
37ec0 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  * text encodings
37ed0 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
37ee0 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
37ef0 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20   SQLITE_UTF8    
37f00 20 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20 49         1    /* I
37f10 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35 36  MP: R-37514-3556
37f20 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  6 */.#define SQL
37f30 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20  ITE_UTF16LE     
37f40 20 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20     2    /* IMP: 
37f50 52 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a 2f  R-03371-37637 */
37f60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
37f70 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33  UTF16BE        3
37f80 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31      /* IMP: R-51
37f90 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65  971-34154 */.#de
37fa0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
37fb0 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20  6          4    
37fc0 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79  /* Use native by
37fd0 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66  te order */.#def
37fe0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20  ine SQLITE_ANY  
37ff0 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f            5    /
38000 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a  * Deprecated */.
38010 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
38020 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20  TF16_ALIGNED  8 
38030 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
38040 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f  eate_collation o
38050 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  nly */../*.** CA
38060 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e  PI3REF: Function
38070 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Flags.**.** The
38080 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79  se constants may
38090 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65   be ORed togethe
380a0 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  r with the .** [
380b0 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72  SQLITE_UTF8 | pr
380c0 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
380d0 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f  oding] as the fo
380e0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  urth argument.**
380f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
38100 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
38110 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
38120 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20  _function16()], 
38130 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  or.** [sqlite3_c
38140 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
38150 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  2()]..*/.#define
38160 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e   SQLITE_DETERMIN
38170 49 53 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a  ISTIC    0x800..
38180 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
38190 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74  Deprecated Funct
381a0 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54  ions.** DEPRECAT
381b0 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  ED.**.** These f
381c0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65  unctions are [de
381d0 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f  precated].  In o
381e0 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e  rder to maintain
381f0 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
38200 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68  mpatibility with
38210 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65   older code, the
38220 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e  se functions con
38230 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20  tinue .** to be 
38240 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65  supported.  Howe
38250 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61  ver, new applica
38260 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f  tions should avo
38270 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  id.** the use of
38280 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
38290 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61 67 65 20  .  To encourage 
382a0 70 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20 61  programmers to a
382b0 76 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20 66 75  void.** these fu
382c0 6e 63 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c  nctions, we will
382d0 20 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77 68 61   not explain wha
382e0 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69  t they do..*/.#i
382f0 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
38300 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c  T_DEPRECATED.SQL
38310 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
38320 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
38330 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
38340 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
38350 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
38360 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69  int sqlite3_expi
38370 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(sqlite3_stmt
38380 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
38390 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
383a0 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69  3_transfer_bindi
383b0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
383c0 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  *, sqlite3_stmt*
383d0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
383e0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
383f0 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
38400 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
38410 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71  PRECATED void sq
38420 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65  lite3_thread_cle
38430 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49  anup(void);.SQLI
38440 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
38450 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  t sqlite3_memory
38460 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76  _alarm(void(*)(v
38470 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
38480 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20  64,int),.       
38490 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
384a0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
384b0 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  64);.#endif../*.
384c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
384d0 61 69 6e 69 6e 67 20 53 51 4c 20 56 61 6c 75 65  aining SQL Value
384e0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
384f0 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a  ite3_value.**.**
38500 20 3c 62 3e 53 75 6d 6d 61 72 79 3a 3c 2f 62 3e   <b>Summary:</b>
38510 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
38520 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 30 20  <table border=0 
38530 63 65 6c 6c 70 61 64 64 69 6e 67 3d 30 20 63 65  cellpadding=0 ce
38540 6c 6c 73 70 61 63 69 6e 67 3d 30 3e 0a 2a 2a 20  llspacing=0>.** 
38550 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
38560 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 3c 2f 62  e3_value_blob</b
38570 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 42  ><td>&rarr;<td>B
38580 4c 4f 42 20 76 61 6c 75 65 0a 2a 2a 20 3c 74 72  LOB value.** <tr
38590 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
385a0 76 61 6c 75 65 5f 64 6f 75 62 6c 65 3c 2f 62 3e  value_double</b>
385b0 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 52 45  <td>&rarr;<td>RE
385c0 41 4c 20 76 61 6c 75 65 0a 2a 2a 20 3c 74 72 3e  AL value.** <tr>
385d0 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 76  <td><b>sqlite3_v
385e0 61 6c 75 65 5f 69 6e 74 3c 2f 62 3e 3c 74 64 3e  alue_int</b><td>
385f0 26 72 61 72 72 3b 3c 74 64 3e 33 32 2d 62 69 74  &rarr;<td>32-bit
38600 20 49 4e 54 45 47 45 52 20 76 61 6c 75 65 0a 2a   INTEGER value.*
38610 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
38620 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
38630 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
38640 64 3e 36 34 2d 62 69 74 20 49 4e 54 45 47 45 52  d>64-bit INTEGER
38650 20 76 61 6c 75 65 0a 2a 2a 20 3c 74 72 3e 3c 74   value.** <tr><t
38660 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 76 61 6c  d><b>sqlite3_val
38670 75 65 5f 70 6f 69 6e 74 65 72 3c 2f 62 3e 3c 74  ue_pointer</b><t
38680 64 3e 26 72 61 72 72 3b 3c 74 64 3e 50 6f 69 6e  d>&rarr;<td>Poin
38690 74 65 72 20 76 61 6c 75 65 0a 2a 2a 20 3c 74 72  ter value.** <tr
386a0 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
386b0 76 61 6c 75 65 5f 74 65 78 74 3c 2f 62 3e 3c 74  value_text</b><t
386c0 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d  d>&rarr;<td>UTF-
386d0 38 20 54 45 58 54 20 76 61 6c 75 65 0a 2a 2a 20  8 TEXT value.** 
386e0 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
386f0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 3c  e3_value_text16<
38700 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
38710 3e 55 54 46 2d 31 36 20 54 45 58 54 20 76 61 6c  >UTF-16 TEXT val