/ Hex Artifact Content
Login

Artifact 16bbb15a5fc53bfd725305ec9a201a7f57df7770749aa758b33a0636946d1bb4:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c  ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a  ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66  .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53  _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f   file.  ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72  us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20  s might include 
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70  nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76  lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65  erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20  atch the macros 
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72  in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72  , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69  e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d  cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68  piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20  ing library and 
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a  header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28  <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51  ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65  ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30  ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c  BER].  ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20  rocessor macro. 
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74   Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73  e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f  ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67  py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74  amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61  he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68  racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20  e hash might be 
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b  different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1e00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1e10: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1e20: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1e30: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1e40: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1e50: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1e60: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1e70: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1e80: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1e90: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1ea0: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1eb0: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1ec0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1ed0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1ee0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1ef0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1f00: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1f10: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1f20: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1f30: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1f40: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1f50: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1f60: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1f70: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1f80: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1f90: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1fa0: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1fb0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1fc0: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1fd0: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1fe0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1ff0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
2000: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
2010: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
2020: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
2030: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
2040: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
2050: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
2060: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
2070: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
2080: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
2090: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
20a0: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
20b0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
20c0: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
20d0: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
20e0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
20f0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
2100: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
2110: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
2120: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
2130: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2140: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2150: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2160: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2170: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
2180: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
2190: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
21a0: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
21b0: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
21c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
21d0: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
21e0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
21f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2200: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
2210: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
2220: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
2230: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2240: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2250: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2260: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
2290: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
22a0: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
22b0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
22c0: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
22d0: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
22e0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
22f0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
2300: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
2310: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
2320: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
2330: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2340: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2350: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2360: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2370: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
2380: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
2390: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
23a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
23b0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
23c0: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
23d0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
23e0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
23f0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
2400: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
2410: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
2420: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2430: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2440: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2450: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2460: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2470: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2480: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2490: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
24a0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
24b0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
24c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
24d0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
24e0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
24f0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
2500: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2510: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
2520: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2530: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2540: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2550: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2560: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2570: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2580: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2590: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
25a0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
25b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
25c0: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
25d0: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
25e0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
25f0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
2600: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
2610: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
2620: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
2630: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2640: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2650: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2660: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2670: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2680: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2690: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
26a0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
26b0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
26c0: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
26d0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
26e0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
26f0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
2700: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
2710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2730: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2740: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2750: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2760: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2770: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2780: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2790: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
27a0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
27b0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
27c0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
27d0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
27e0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
27f0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
2800: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2810: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
2820: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
2830: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2840: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2850: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2860: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2870: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2880: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2890: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
28a0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
28b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
28c0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
28d0: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
28e0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
28f0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
2900: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
2910: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2920: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
2930: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2940: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2950: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2960: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2970: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2980: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2990: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
29a0: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
29b0: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
29c0: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
29d0: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
29e0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
29f0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
2a00: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2a10: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2a20: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
2a30: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2a40: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2a50: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2a60: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2a70: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2a80: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2a90: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2aa0: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45  ;.# ifdef SQLITE
2ab0: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20  _UINT64_TYPE.   
2ac0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2ad0: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  UINT64_TYPE sqli
2ae0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73  te_uint64;.# els
2af0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20  e  .    typedef 
2b00: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2b20: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69  e_uint64;.# endi
2b30: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  f.#elif defined(
2b40: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2b50: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2b60: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2b70: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2b80: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2b90: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2ba0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2bb0: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2bc0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2bd0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2be0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2bf0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2c00: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2c10: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2c30: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2c40: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2c50: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2c60: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2c70: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2c80: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2c90: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2ca0: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2cb0: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2cc0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2cd0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2ce0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2cf0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2d00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2d10: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2d20: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2d30: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2d40: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2d50: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2d60: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2d70: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2d80: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2d90: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2da0: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2db0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2dc0: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2dd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2de0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2df0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2e00: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2e10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2e20: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2e30: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2e40: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2e50: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2e60: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2e80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e90: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2ea0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2eb0: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2ec0: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ed0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2ee0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2ef0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2f00: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2f10: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2f20: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2f30: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2f40: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2f50: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2f60: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2f70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2f80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2f90: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2fa0: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2fb0: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2fc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fd0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2fe0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2ff0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
3000: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
3010: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
3020: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
3030: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
3040: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
3050: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
3060: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
3070: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
3080: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
3090: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
30a0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
30b0: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
30c0: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
30d0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
30e0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
30f0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
3100: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
3110: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
3120: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
3130: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3140: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3150: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
3160: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3170: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3180: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3190: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
31a0: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
31b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
31c0: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
31d0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
31e0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31f0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
3200: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
3210: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
3220: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
3230: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3240: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3250: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3260: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3270: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3280: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3290: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
32a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32b0: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
32c0: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
32d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
32e0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
32f0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
3300: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
3310: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3320: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3330: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3340: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3350: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3360: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3370: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3380: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3390: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
33a0: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
33b0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
33c0: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
33d0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
33e0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
33f0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3400: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3410: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3420: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3440: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3450: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3460: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3470: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3480: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3490: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
34a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
34b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
34c0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
34d0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
34e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
34f0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3500: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3510: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3520: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3530: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3540: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3550: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3560: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3570: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3580: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3590: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35a0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
35b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
35c0: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
35d0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
35e0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
35f0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
3600: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
3610: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
3620: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3630: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3640: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3650: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3660: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3670: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3680: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3690: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
36a0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
36b0: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
36c0: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
36d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
36e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
36f0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
3700: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
3710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
3720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
3730: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3740: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3750: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
3760: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
3770: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
3780: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
3790: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
37a0: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
37b0: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
37c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
37e0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
37f0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
3800: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
3810: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
3820: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
3830: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
3840: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
3850: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
3860: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3870: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
3880: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
3890: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
38a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
38b0: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
38c0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
38d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
38e0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
38f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
3900: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
3910: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
3920: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
3930: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3940: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3950: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3960: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
3970: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3980: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
3990: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
39a0: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
39b0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
39c0: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
39d0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
39e0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
39f0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
3a00: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
3a10: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
3a20: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
3a30: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3a40: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
3a50: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
3a60: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3a70: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3a80: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
3a90: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3aa0: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3ab0: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3ac0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3ad0: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
3ae0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3af0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3b00: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
3b10: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
3b20: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
3b30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3b40: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
3b50: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3b60: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
3b70: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
3b90: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3ba0: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3bb0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3bc0: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3bd0: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3be0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3bf0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3c00: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3c10: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3c20: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3c30: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3c40: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3c50: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3c60: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3c70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3c90: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3ca0: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3cb0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3cc0: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3cd0: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3ce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3cf0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3d00: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3d10: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3d20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3d30: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3d40: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3d50: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3d60: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3d70: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3d80: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3d90: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3da0: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3db0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3dc0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3dd0: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3de0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3df0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3e00: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3e10: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3e20: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3e30: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3e40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3e60: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3e70: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e80: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3e90: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3ea0: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3eb0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3ec0: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3ed0: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ee0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3ef0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3f00: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3f10: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3f20: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3f30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3f40: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3f50: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3f60: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3f70: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3f80: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3f90: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3fa0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3fb0: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3fc0: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3fd0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3fe0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3ff0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
4000: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
4010: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
4020: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
4030: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
4040: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
4050: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
4060: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
4070: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
4080: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
4090: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
40a0: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
40b0: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
40c0: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
40d0: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
40e0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
40f0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
4100: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
4110: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
4120: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
4130: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
4140: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4150: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
4160: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
4170: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
4180: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
4190: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
41a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
41b0: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
41c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
41d0: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
41e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
41f0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
4200: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
4210: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4220: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
4230: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4240: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4250: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4260: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4270: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
4280: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
4290: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
42a0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
42b0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
42c0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
42d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
42e0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
42f0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
4300: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4310: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4330: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4340: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4350: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4370: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4380: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4390: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
43a0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
43b0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
43c0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
43d0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
43e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4400: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4410: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4420: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4430: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4450: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4460: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4470: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4480: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4490: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
44a0: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
44b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
44c0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
44d0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
44e0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
44f0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
4500: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4510: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4520: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4530: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4540: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4550: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4560: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4570: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4580: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4590: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
45a0: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
45b0: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
45c0: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
45d0: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
45e0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
45f0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4610: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
4620: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72  /* Generic error
4630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4640: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4650: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4660: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4670: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4680: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4690: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
46a0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
46b0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
46c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
46d0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
46e0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
46f0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
4700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4710: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
4720: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4730: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4760: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4770: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4780: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4790: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
47a0: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
47b0: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
47c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
47d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
47e0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
47f0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
4800: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
4810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4820: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4830: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4840: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4850: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4870: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4880: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4890: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
48a0: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
48b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
48c0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
48d0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
48e0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
48f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4900: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
4910: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
4920: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4930: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4940: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4950: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4960: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4970: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4980: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4990: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
49a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
49b0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
49c0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
49d0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
49e0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
49f0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
4a00: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
4a10: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
4a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4a30: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4a40: 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20 6f  * Internal use o
4a50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
4a60: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4a70: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4a80: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4a90: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4aa0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4ab0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4ac0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
4ad0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
4ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4af0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4b00: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4b10: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4b20: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4b30: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4b40: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4b50: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4b60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b70: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4b80: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4b90: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bb0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4bc0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4bd0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4be0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4c00: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4c10: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4c20: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4c30: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4c40: 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 20      24   /* Not 
4c50: 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
4c60: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4c70: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4c80: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4c90: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4ca0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4cb0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4cc0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4cd0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
4ce0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
4cf0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
4d10: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4d20: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4d30: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4d50: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4d60: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4d70: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4d90: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4da0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4db0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4dc0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4dd0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4de0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4df0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4e00: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4e10: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4e20: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4e30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4e40: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4e50: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4e60: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4e70: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4e80: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4e90: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4ea0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4eb0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ec0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4ed0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4ee0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4ef0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4f00: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4f10: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4f20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f30: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4f40: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4f50: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4f60: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4f70: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4f80: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4f90: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4fa0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4fb0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4fc0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4fd0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4fe0: 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33  .3.8 [dateof:3.3
4ff0: 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72  .8].** and later
5000: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
5010: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
5020: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
5030: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
5040: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
5050: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
5060: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b   errors. These [
5070: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
5080: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c  codes] are enabl
5090: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
50a0: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
50b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
50c0: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
50d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
50e0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
50f0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68  ()] API.  Or, th
5100: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20  e extended code 
5110: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20  for.** the most 
5120: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e  recent error can
5130: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69   be obtained usi
5140: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
5150: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
5160: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
5170: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53 53  QLITE_ERROR_MISS
5180: 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28 53  ING_COLLSEQ   (S
5190: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 31  QLITE_ERROR | (1
51a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
51b0: 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52 59  LITE_ERROR_RETRY
51c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
51d0: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32 3c  LITE_ERROR | (2<
51e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
51f0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
5200: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5210: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5220: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5230: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
5240: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
5260: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5270: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5280: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
52a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52b0: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
52c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52d0: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
52e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52f0: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5300: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5310: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5330: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
5340: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5350: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5370: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5390: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
53a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53b0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
53c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53d0: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
53f0: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5400: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5410: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5470: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5490: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54b0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54d0: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54f0: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5510: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5530: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5540: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
5550: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
5560: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5570: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5580: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5590: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
55a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55b0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
55c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55d0: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
55e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55f0: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5600: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5610: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5620: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5630: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5640: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5650: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
5660: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5670: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5680: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5690: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
56a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56b0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
56c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56d0: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
56e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56f0: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5700: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5710: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5720: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5730: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5740: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5750: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5760: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5770: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5780: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5790: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
57a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57b0: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
57c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57d0: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
57e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57f0: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5800: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5810: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5820: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5830: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
5840: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5850: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
5860: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5870: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
5880: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5890: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
58a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58b0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
58c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58d0: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
58e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58f0: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20  _BEGIN_ATOMIC   
5900: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5910: 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66   | (29<<8)).#def
5920: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5930: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20  _COMMIT_ATOMIC  
5940: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5950: 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66   | (30<<8)).#def
5960: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5970: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
5980: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5990: 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66   | (31<<8)).#def
59a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
59b0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
59c0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
59d0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
59e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
59f0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5a00: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5a10: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5a30: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5a40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5a50: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5a60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5a70: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5a80: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5a90: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5aa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ab0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5ac0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5ad0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5ae0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5af0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5b00: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5b10: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5b20: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b30: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5b40: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5b50: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5b60: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5b70: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 44  QLITE_CANTOPEN_D
5b80: 49 52 54 59 57 41 4c 20 20 20 20 20 20 20 28 53  IRTYWAL       (S
5b90: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5ba0: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5bb0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5bc0: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
5bd0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5be0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5bf0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5c00: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5c10: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5c20: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<8)).#def
5c30: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5c40: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
5c50: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5c60: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  NLY | (2<<8)).#d
5c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5c80: 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20  DONLY_ROLLBACK  
5c90: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5ca0: 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a  DONLY | (3<<8)).
5cb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5cc0: 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20  EADONLY_DBMOVED 
5cd0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5ce0: 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29  EADONLY | (4<<8)
5cf0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5d00: 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49 4e  _READONLY_CANTIN
5d10: 49 54 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  IT       (SQLITE
5d20: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c 3c  _READONLY | (5<<
5d30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5d40: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52 45  TE_READONLY_DIRE
5d50: 43 54 4f 52 59 20 20 20 20 20 20 28 53 51 4c 49  CTORY      (SQLI
5d60: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 36  TE_READONLY | (6
5d70: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5d80: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
5d90: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
5da0: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
5db0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5dc0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5dd0: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  HECK        (SQL
5de0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5df0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5e00: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5e10: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20  NT_COMMITHOOK   
5e20: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5e30: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  NT | (2<<8)).#de
5e40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5e50: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45  TRAINT_FOREIGNKE
5e60: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5e70: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29  TRAINT | (3<<8))
5e80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e90: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54  CONSTRAINT_FUNCT
5ea0: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ION     (SQLITE_
5eb0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c  CONSTRAINT | (4<
5ec0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5ed0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e  ITE_CONSTRAINT_N
5ee0: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c  OTNULL      (SQL
5ef0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5f00: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5f10: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5f20: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20  NT_PRIMARYKEY   
5f30: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5f40: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  NT | (6<<8)).#de
5f50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5f60: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20  TRAINT_TRIGGER  
5f70: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5f80: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29  TRAINT | (7<<8))
5f90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fa0: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55  CONSTRAINT_UNIQU
5fb0: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  E       (SQLITE_
5fc0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c  CONSTRAINT | (8<
5fd0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5fe0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56  ITE_CONSTRAINT_V
5ff0: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAB         (SQL
6000: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
6010: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
6020: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
6030: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20  NT_ROWID        
6040: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6050: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65  NT |(10<<8)).#de
6060: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
6070: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
6080: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
6090: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
60a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
60b0: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
60c0: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
60d0: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
60e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
60f0: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
6100: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
6110: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ING | (1<<8)).#d
6120: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
6130: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20  H_USER          
6140: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54       (SQLITE_AUT
6150: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  H | (1<<8)).#def
6160: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f  ine SQLITE_OK_LO
6170: 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20  AD_PERMANENTLY  
6180: 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20     (SQLITE_OK | 
6190: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
61a0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
61b0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
61c0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
61d0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
61e0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
61f0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
6200: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
6210: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
6220: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
6230: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
6240: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
6250: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
6260: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
6270: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6280: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
6290: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
62a0: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
62b0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
62c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
62d0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
62e0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
62f0: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
6300: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6310: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6320: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
6330: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6340: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
6350: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6360: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6370: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
6380: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
6390: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
63a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
63b0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
63c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
63d0: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
63e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
63f0: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
6400: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6410: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
6420: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6430: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
6440: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6450: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
6460: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6470: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6480: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
6490: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
64a0: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
64b0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
64c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
64d0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
64e0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
64f0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6500: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6510: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
6520: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
6530: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6550: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
6560: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
6570: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6580: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6590: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
65a0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
65b0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
65c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
65d0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
65e0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
65f0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6600: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6610: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
6620: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
6630: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6640: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6650: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
6660: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
6670: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6680: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6690: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
66a0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
66b0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
66c0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
66d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
66e0: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
66f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
6700: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6710: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6720: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6730: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
6740: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
6750: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6760: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6770: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6780: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
6790: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
67a0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
67b0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
67c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
67d0: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
67e0: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
67f0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6800: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
6810: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6820: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
6830: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
6840: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
6850: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
6860: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
6870: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
6880: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
6890: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
68a0: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
68b0: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
68c0: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
68d0: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
68e0: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
68f0: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
6900: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
6910: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
6920: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
6930: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
6940: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
6950: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
6960: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
6970: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6980: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
6990: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
69a0: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
69b0: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
69c0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
69d0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
69e0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
69f0: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
6a00: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
6a10: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
6a20: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
6a30: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
6a40: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
6a50: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
6a60: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
6a70: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6a80: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
6a90: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
6aa0: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
6ab0: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
6ac0: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
6ad0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
6ae0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
6af0: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
6b00: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
6b10: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
6b20: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
6b30: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6b40: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
6b50: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
6b60: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
6b70: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
6b80: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
6b90: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
6ba0: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
6bb0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6bc0: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
6bd0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
6be0: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
6bf0: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
6c00: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
6c10: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
6c20: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
6c30: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
6c40: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
6c50: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
6c60: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
6c70: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
6c80: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
6c90: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
6ca0: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
6cb0: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
6cc0: 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51  changed.  The SQ
6cd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
6ce0: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
6cf0: 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74  .** flag indicat
6d00: 65 73 20 74 68 61 74 20 61 20 66 69 6c 65 20 63  es that a file c
6d10: 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64  annot be deleted
6d20: 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65   when open.  The
6d30: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  .** SQLITE_IOCAP
6d40: 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20  _IMMUTABLE flag 
6d50: 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
6d60: 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a  he file is on.**
6d70: 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61   read-only media
6d80: 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63   and cannot be c
6d90: 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70  hanged even by p
6da0: 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a  rocesses with.**
6db0: 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c   elevated privil
6dc0: 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eges..**.** The 
6dd0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54  SQLITE_IOCAP_BAT
6de0: 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  CH_ATOMIC proper
6df0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ty means that th
6e00: 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20  e underlying.** 
6e10: 66 69 6c 65 73 79 73 74 65 6d 20 73 75 70 70 6f  filesystem suppo
6e20: 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69 70  rts doing multip
6e30: 6c 65 20 77 72 69 74 65 20 6f 70 65 72 61 74 69  le write operati
6e40: 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20 77  ons atomically w
6e50: 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72 69  hen those.** wri
6e60: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  te operations ar
6e70: 65 20 62 72 61 63 6b 65 74 65 64 20 62 79 20 5b  e bracketed by [
6e80: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
6e90: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
6ea0: 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   and.** [SQLITE_
6eb0: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
6ec0: 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a 23  MIC_WRITE]..*/.#
6ed0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6ee0: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
6ef0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6f00: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
6f10: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6f20: 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20  C512            
6f30: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
6f40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6f50: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
6f60: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6f70: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
6f80: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
6f90: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
6fa0: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
6fb0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6fc0: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
6fd0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
6fe0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6ff0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20  _IOCAP_ATOMIC8K 
7000: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
7010: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65  00000020.#define
7020: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
7030: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20  OMIC16K         
7040: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
7050: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7060: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
7070: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
7080: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
7090: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
70a0: 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20  IC64K           
70b0: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
70c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
70d0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20  AP_SAFE_APPEND  
70e0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
70f0: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
7100: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
7110: 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  TIAL            
7120: 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66   0x00000400.#def
7130: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
7140: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
7150: 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38  N_OPEN  0x000008
7160: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
7170: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
7180: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30  E_OVERWRITE    0
7190: 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e  x00001000.#defin
71a0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49  e SQLITE_IOCAP_I
71b0: 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20 20  MMUTABLE        
71c0: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
71d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
71e0: 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d  IOCAP_BATCH_ATOM
71f0: 49 43 20 20 20 20 20 20 20 20 20 20 20 30 78 30  IC           0x0
7200: 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0004000../*.** C
7210: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
7220: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
7230: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
7240: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
7250: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
7260: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
7270: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
7280: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
7290: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
72a0: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
72b0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
72c0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
72d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
72e0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
72f0: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
7300: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
7310: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
7320: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
7330: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
7340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7350: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
7360: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
7370: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
7380: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
7390: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
73a0: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
73b0: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
73c0: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
73d0: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
73e0: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
73f0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
7400: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
7410: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
7420: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
7430: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
7440: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
7450: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
7460: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
7470: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
7480: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
7490: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
74a0: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
74b0: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
74c0: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
74d0: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
74e0: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
74f0: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
7500: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
7510: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
7520: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
7530: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
7540: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
7550: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
7560: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
7570: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
7580: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
7590: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
75a0: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
75b0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
75c0: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
75d0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
75e0: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
75f0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
7600: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
7610: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
7620: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
7630: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
7640: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
7650: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
7660: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
7670: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
7680: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
7690: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
76a0: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
76b0: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
76c0: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
76d0: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
76e0: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
76f0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
7700: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
7710: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
7720: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
7730: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
7740: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
7750: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
7760: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
7770: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
7780: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
7790: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
77a0: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
77b0: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
77c0: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
77d0: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
77e0: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
77f0: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
7800: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
7810: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
7820: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
7830: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
7840: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
7850: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
7860: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
7870: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
7880: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
7890: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
78a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
78b0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
78c0: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
78d0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
78e0: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
78f0: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
7900: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7910: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
7920: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
7930: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
7940: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
7950: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
7960: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
7970: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
7980: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
7990: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
79a0: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
79b0: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
79c0: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
79d0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
79e0: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
79f0: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
7a00: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
7a10: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
7a20: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
7a30: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
7a40: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
7a50: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
7a60: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
7a70: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
7a80: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
7a90: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
7aa0: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
7ab0: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
7ac0: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
7ad0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
7ae0: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
7af0: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
7b00: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
7b10: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
7b20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
7b30: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
7b40: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
7b50: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
7b60: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7b70: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
7b80: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
7b90: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
7ba0: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
7bb0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7bc0: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
7bd0: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
7be0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7bf0: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
7c00: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
7c10: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
7c20: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7c30: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
7c40: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
7c50: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
7c60: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
7c70: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
7c80: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
7c90: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
7ca0: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
7cb0: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
7cc0: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
7cd0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
7ce0: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
7cf0: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
7d00: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7d10: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
7d20: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7d30: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
7d40: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
7d50: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
7d60: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7d70: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
7d80: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
7d90: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
7da0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7db0: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
7dc0: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
7dd0: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
7de0: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
7df0: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
7e00: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
7e10: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
7e20: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
7e30: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7e40: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
7e50: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7e60: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
7e70: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
7e80: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7e90: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
7ea0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
7eb0: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
7ec0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
7ed0: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
7ee0: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
7ef0: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
7f00: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
7f10: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
7f20: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
7f30: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
7f40: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
7f50: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
7f60: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
7f70: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
7f80: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
7f90: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
7fa0: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
7fb0: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
7fc0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
7fd0: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
7fe0: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
7ff0: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
8000: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
8010: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
8020: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
8030: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
8040: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
8050: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
8060: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
8070: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
8080: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
8090: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
80a0: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
80b0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
80c0: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
80d0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
80e0: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
80f0: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
8100: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
8110: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
8120: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
8130: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
8140: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
8150: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
8160: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
8170: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
8180: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
8190: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
81a0: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
81b0: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
81c0: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
81d0: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
81e0: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
81f0: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
8200: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
8210: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
8220: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
8230: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
8240: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
8250: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
8260: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
8270: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8280: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
8290: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
82a0: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
82b0: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
82c0: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
82d0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
82e0: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
82f0: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
8300: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
8310: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
8320: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
8330: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
8340: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
8350: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
8360: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
8370: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
8380: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
8390: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
83a0: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
83b0: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
83c0: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
83d0: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
83e0: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
83f0: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
8400: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
8410: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
8420: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
8430: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
8440: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
8450: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
8460: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
8470: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
8480: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
8490: 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A [file control 
84a0: 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f  opcodes | list o
84b0: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
84c0: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
84d0: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
84e0: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
84f0: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
8500: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
8510: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
8520: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
8530: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
8540: 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20  conflicts.  VFS 
8550: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
8560: 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
8570: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
8580: 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74  D] for file cont
8590: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74  rol opcodes that
85a0: 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
85b0: 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a  recognize..**.**
85c0: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
85d0: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
85e0: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
85f0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
8600: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
8610: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
8620: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
8630: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
8640: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
8650: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
8660: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
8670: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
8680: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
8690: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
86a0: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
86b0: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
86c0: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
86d0: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
86e0: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
86f0: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
8700: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
8710: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8720: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8730: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
8740: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
8750: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
8760: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8770: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
8780: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8790: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
87a0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
87b0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
87c0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
87d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
87e0: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
87f0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8800: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
8810: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8820: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
8830: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8840: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
8850: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
8860: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c  EQUENTIAL].** <l
8870: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8880: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
8890: 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20  N_OPEN].** <li> 
88a0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f  [SQLITE_IOCAP_PO
88b0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
88c0: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
88d0: 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
88e0: 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  LE].** <li> [SQL
88f0: 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f  ITE_IOCAP_BATCH_
8900: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ATOMIC].** </ul>
8910: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
8920: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
8930: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
8940: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
8950: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
8960: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8970: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8980: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
8990: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
89a0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
89b0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
89c0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
89d0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
89e0: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
89f0: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
8a00: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
8a10: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8a20: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
8a30: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
8a40: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
8a50: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
8a60: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
8a70: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
8a80: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
8a90: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
8aa0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
8ab0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
8ac0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
8ad0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8ae0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
8af0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8b00: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
8b10: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
8b20: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
8b30: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
8b40: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
8b50: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
8b60: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
8b70: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
8b80: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
8b90: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
8ba0: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
8bb0: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
8bc0: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
8bd0: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
8be0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
8bf0: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
8c00: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
8c10: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
8c20: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
8c30: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
8c40: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
8c50: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
8c60: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
8c70: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
8c80: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
8c90: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
8ca0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
8cb0: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
8cc0: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
8cd0: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
8ce0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8cf0: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
8d00: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
8d10: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
8d20: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8d30: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
8d40: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
8d50: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
8d60: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
8d70: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
8d80: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
8d90: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
8da0: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
8db0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
8dc0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8dd0: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
8de0: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
8df0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8e00: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
8e10: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
8e20: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8e30: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
8e40: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
8e50: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
8e60: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
8e70: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
8e80: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
8e90: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
8ea0: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
8eb0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8ec0: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
8ed0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
8ee0: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
8ef0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8f00: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
8f10: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
8f20: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74  file*);.  /* Met
8f30: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
8f40: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
8f50: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53   1 */.  int (*xS
8f60: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  hmMap)(sqlite3_f
8f70: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69  ile*, int iPg, i
8f80: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f  nt pgsz, int, vo
8f90: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a  id volatile**);.
8fa0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b    int (*xShmLock
8fb0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8fc0: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74   int offset, int
8fd0: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a   n, int flags);.
8fe0: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72    void (*xShmBar
8ff0: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69  rier)(sqlite3_fi
9000: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  le*);.  int (*xS
9010: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33  hmUnmap)(sqlite3
9020: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65  _file*, int dele
9030: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65  teFlag);.  /* Me
9040: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
9050: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
9060: 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 2 */.  int (*x
9070: 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66  Fetch)(sqlite3_f
9080: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
9090: 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69  t64 iOfst, int i
90a0: 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b  Amt, void **pp);
90b0: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63  .  int (*xUnfetc
90c0: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
90d0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
90e0: 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b  iOfst, void *p);
90f0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
9100: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
9110: 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20  r version 3 */. 
9120: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d   /* Additional m
9130: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64  ethods may be ad
9140: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
9150: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  leases */.};../*
9160: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
9170: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74  andard File Cont
9180: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b  rol Opcodes.** K
9190: 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63  EYWORDS: {file c
91a0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20  ontrol opcodes} 
91b0: 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  {file control op
91c0: 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  code}.**.** Thes
91d0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
91e0: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
91f0: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
9200: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
9210: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
9220: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
9230: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
9240: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9250: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
9260: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ace..**.** <ul>.
9270: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9280: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
9290: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
92a0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
92b0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
92c0: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
92d0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
92e0: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
92f0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
9300: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
9310: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
9320: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
9330: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
9340: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
9350: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
9360: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
9370: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
9380: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
9390: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
93a0: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
93b0: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
93c0: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
93d0: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
93e0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
93f0: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
9400: 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f  testing and is o
9410: 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68  nly available wh
9420: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  en the SQLITE_TE
9430: 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  ST.** compile-ti
9440: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  me option is use
9450: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
9460: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
9470: 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _HINT]].** The [
9480: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
9490: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
94a0: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
94b0: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
94c0: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
94d0: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
94e0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
94f0: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
9500: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
9510: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
9520: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
9530: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
9540: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
9550: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
9560: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
9570: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
9580: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
9590: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
95a0: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
95b0: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
95c0: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
95d0: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
95e0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
95f0: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
9600: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9610: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
9620: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
9630: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
9640: 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  SIZE] opcode is 
9650: 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20  used to request 
9660: 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20  that the VFS.** 
9670: 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e  extends and trun
9680: 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61  cates the databa
9690: 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b  se file in chunk
96a0: 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63  s of a size spec
96b0: 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
96c0: 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68  user. The fourth
96d0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
96e0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
96f0: 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a  ol()] should .**
9700: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74   point to an int
9710: 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20  eger (type int) 
9720: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
9730: 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f  ew chunk-size to
9740: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20   use.** for the 
9750: 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61  nominated databa
9760: 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64  se. Allocating d
9770: 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61  atabase file spa
9780: 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63  ce in large.** c
9790: 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61  hunks (say 1MB a
97a0: 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72  t a time), may r
97b0: 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65  educe file-syste
97c0: 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20  m fragmentation 
97d0: 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70  and.** improve p
97e0: 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f  erformance on so
97f0: 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a  me systems..**.*
9800: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9810: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
9820: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  R]].** The [SQLI
9830: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
9840: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73  INTER] opcode is
9850: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
9860: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
9870: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
9880: 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69  e] object associ
9890: 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74  ated with a part
98a0: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
98b0: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
98c0: 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45  See also [SQLITE
98d0: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
98e0: 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  OINTER]..**.** <
98f0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9900: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45  L_JOURNAL_POINTE
9910: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  R]].** The [SQLI
9920: 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c  TE_FCNTL_JOURNAL
9930: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
9940: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
9950: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
9960: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
9970: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
9980: 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
9990: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65   journal file (e
99a0: 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f  ither.** the [ro
99b0: 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20  llback journal] 
99c0: 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68  or the [write-ah
99d0: 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20  ead log]) for a 
99e0: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
99f0: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
9a00: 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51  n.  See also [SQ
9a10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
9a20: 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20  POINTER]..**.** 
9a30: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9a40: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d  TL_SYNC_OMITTED]
9a50: 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69  ].** No longer i
9a60: 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  n use..**.** <li
9a70: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9a80: 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SYNC]].** The [S
9a90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
9aa0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65  ] opcode is gene
9ab0: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  rated internally
9ac0: 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a   by SQLite and.*
9ad0: 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46  * sent to the VF
9ae0: 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65  S immediately be
9af0: 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d  fore the xSync m
9b00: 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
9b10: 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73   on a.** databas
9b20: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  e file descripto
9b30: 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53  r. Or, if the xS
9b40: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f  ync method is no
9b50: 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65  t invoked .** be
9b60: 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68  cause the user h
9b70: 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51  as configured SQ
9b80: 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50  Lite with .** [P
9b90: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
9ba0: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
9bb0: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69  ronous=OFF] it i
9bc0: 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61  s invoked in pla
9bd0: 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53  ce .** of the xS
9be0: 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d  ync method. In m
9bf0: 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70  ost cases, the p
9c00: 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20  ointer argument 
9c10: 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74  passed with.** t
9c20: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
9c30: 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65   is NULL. Howeve
9c40: 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61  r, if the databa
9c50: 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67  se file is being
9c60: 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61   synced.** as pa
9c70: 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61  rt of a multi-da
9c80: 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74  tabase commit, t
9c90: 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  he argument poin
9ca0: 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d  ts to a nul-term
9cb0: 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
9cc0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
9cd0: 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73  transactions mas
9ce0: 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  ter-journal file
9cf0: 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61   name. VFSes tha
9d00: 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65  t .** do not nee
9d10: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68  d this signal sh
9d20: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
9d30: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
9d40: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a  . Applications .
9d50: 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ** should not ca
9d60: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ll [sqlite3_file
9d70: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
9d80: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20   this opcode as 
9d90: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a  doing so may .**
9da0: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
9db0: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
9dc0: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
9dd0: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
9de0: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  it.  .**.** <li>
9df0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  [[SQLITE_FCNTL_C
9e00: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d  OMMIT_PHASETWO]]
9e10: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9e20: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
9e30: 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73  SETWO] opcode is
9e40: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
9e50: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a  nally by SQLite.
9e60: 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74  ** and sent to t
9e70: 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74  he VFS after a t
9e80: 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62  ransaction has b
9e90: 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d  een committed im
9ea0: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74  mediately.** but
9eb0: 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61   before the data
9ec0: 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64  base is unlocked
9ed0: 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  . VFSes that do 
9ee0: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69  not need this si
9ef0: 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73  gnal.** should s
9f00: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74  ilently ignore t
9f10: 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c  his opcode. Appl
9f20: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
9f30: 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  not call.** [sql
9f40: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9f50: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
9f60: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
9f70: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68  o may disrupt th
9f80: 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  e .** operation 
9f90: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
9fa0: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
9fb0: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
9fc0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9fd0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
9fe0: 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65  _RETRY]].** ^The
9ff0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
a000: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f  IN32_AV_RETRY] o
a010: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
a020: 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d   configure autom
a030: 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f  atic.** retry co
a040: 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61  unts and interva
a050: 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64  ls for certain d
a060: 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  isk I/O operatio
a070: 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69  ns for the.** wi
a080: 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f  ndows [VFS] in o
a090: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
a0a0: 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68  robustness in th
a0b0: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a  e presence of.**
a0c0: 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67   anti-virus prog
a0d0: 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c  rams.  By defaul
a0e0: 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56  t, the windows V
a0f0: 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69  FS will retry fi
a100: 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65  le read,.** file
a110: 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65   write, and file
a120: 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f   delete operatio
a130: 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65  ns up to 10 time
a140: 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a  s, with a delay.
a150: 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65  ** of 25 millise
a160: 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65  conds before the
a170: 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64   first retry and
a180: 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20   with the delay 
a190: 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79  increasing.** by
a1a0: 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32   an additional 2
a1b0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77  5 milliseconds w
a1c0: 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75  ith each subsequ
a1d0: 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73  ent retry.  This
a1e0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77  .** opcode allow
a1f0: 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75  s these two valu
a200: 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61  es (10 retries a
a210: 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  nd 25 millisecon
a220: 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20  ds of delay).** 
a230: 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20  to be adjusted. 
a240: 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20   The values are 
a250: 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20  changed for all 
a260: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
a270: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74  ions.** within t
a280: 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e  he same process.
a290: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69    The argument i
a2a0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
a2b0: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a  n array of two.*
a2c0: 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65  * integers where
a2d0: 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67   the first integ
a2e0: 65 72 20 69 73 20 74 68 65 20 6e 65 77 20 72 65  er is the new re
a2f0: 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68  try count and th
a300: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65  e second.** inte
a310: 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79  ger is the delay
a320: 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74  .  If either int
a330: 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eger is negative
a340: 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69  , then the setti
a350: 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  ng.** is not cha
a360: 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64  nged but instead
a370: 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
a380: 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67   of that setting
a390: 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69   is written.** i
a3a0: 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e  nto the array en
a3b0: 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68  try, allowing th
a3c0: 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20  e current retry 
a3d0: 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a  settings to be.*
a3e0: 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20  * interrogated. 
a3f0: 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72   The zDbName par
a400: 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65  ameter is ignore
a410: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
a420: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
a430: 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68  IST_WAL]].** ^Th
a440: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a450: 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63  PERSIST_WAL] opc
a460: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
a470: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
a480: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57  ** persistent [W
a490: 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64  AL | Write Ahead
a4a0: 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20   Log] setting.  
a4b0: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
a4c0: 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69  auxiliary.** wri
a4d0: 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64  te ahead log and
a4e0: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
a4f0: 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72  iles used for tr
a500: 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
a510: 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74  l.** are automat
a520: 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77  ically deleted w
a530: 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63  hen the latest c
a540: 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65  onnection to the
a550: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f   database.** clo
a560: 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65  ses.  Setting pe
a570: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
a580: 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66  e causes those f
a590: 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20  iles to persist 
a5a0: 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20  after.** close. 
a5b0: 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20   Persisting the 
a5c0: 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20  files is useful 
a5d0: 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65  when other proce
a5e0: 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  sses that do not
a5f0: 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70  .** have write p
a600: 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65  ermission on the
a610: 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61   directory conta
a620: 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  ining the databa
a630: 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20  se file want.** 
a640: 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61  to read the data
a650: 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68  base file, as th
a660: 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64  e WAL and shared
a670: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75   memory files mu
a680: 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f  st exist.** in o
a690: 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74  rder for the dat
a6a0: 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64  abase to be read
a6b0: 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74  able.  The fourt
a6c0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
a6d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
a6e0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74  control()] for t
a6f0: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c  his opcode shoul
a700: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  d be a pointer t
a710: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  o an integer..**
a720: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73   That integer is
a730: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65   0 to disable pe
a740: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
a750: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
a760: 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57   persistent.** W
a770: 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  AL mode.  If the
a780: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
a790: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
a7a0: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
a7b0: 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70  current.** WAL p
a7c0: 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69  ersistence setti
a7d0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
a7e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
a7f0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
a800: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a810: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a820: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70  FE_OVERWRITE] op
a830: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
a840: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
a850: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22  .** persistent "
a860: 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72  powersafe-overwr
a870: 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73  ite" or "PSOW" s
a880: 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f  etting.  The PSO
a890: 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74  W setting.** det
a8a0: 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c  ermines the [SQL
a8b0: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
a8c0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62  AFE_OVERWRITE] b
a8d0: 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65  it of the.** xDe
a8e0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
a8f0: 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65  ics methods. The
a900: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
a910: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
a920: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
a930: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
a940: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
a950: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
a960: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
a970: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
a980: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  ble zero-damage 
a990: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
a9a0: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a  ble zero-damage.
a9b0: 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ** mode.  If the
a9c0: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
a9d0: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
a9e0: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
a9f0: 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d  current.** zero-
aa00: 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74  damage mode sett
aa10: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
aa20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
aa30: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
aa40: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
aa50: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
aa60: 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  e is invoked by 
aa70: 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65  SQLite after ope
aa80: 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20  ning.** a write 
aa90: 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69  transaction to i
aaa0: 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e  ndicate that, un
aab0: 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65  less it is rolle
aac0: 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a  d back for some.
aad0: 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65  ** reason, the e
aae0: 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66  ntire database f
aaf0: 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72  ile will be over
ab00: 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63  written by the c
ab10: 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73  urrent .** trans
ab20: 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20  action. This is 
ab30: 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f  used by VACUUM o
ab40: 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
ab50: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
ab60: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a  NTL_VFSNAME]].**
ab70: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
ab80: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63  NTL_VFSNAME] opc
ab90: 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ode can be used 
aba0: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61  to obtain the na
abb0: 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56  mes of.** all [V
abc0: 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53  FSes] in the VFS
abd0: 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d   stack.  The nam
abe0: 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46  es are of all VF
abf0: 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a  S shims and the.
ac00: 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d  ** final bottom-
ac10: 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72  level VFS are wr
ac20: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
ac30: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
ac40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
ac50: 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72  loc()] and the r
ac60: 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20  esult is stored 
ac70: 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  in the char* var
ac80: 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68  iable.** that th
ac90: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
aca0: 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66  er of [sqlite3_f
acb0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70  ile_control()] p
acc0: 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65  oints to..** The
acd0: 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f   caller is respo
ace0: 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69  nsible for freei
acf0: 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68  ng the memory wh
ad00: 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74  en done.  As wit
ad10: 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f  h.** all file-co
ad20: 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74  ntrol actions, t
ad30: 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61  here is no guara
ad40: 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77  ntee that this w
ad50: 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  ill actually.** 
ad60: 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61  do anything.  Ca
ad70: 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69  llers should ini
ad80: 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72  tialize the char
ad90: 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20  * variable to a 
ada0: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
adb0: 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c  in case this fil
adc0: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74  e-control is not
add0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54   implemented.  T
ade0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
adf0: 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20  .** is intended 
ae00: 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75  for diagnostic u
ae10: 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c  se only..**.** <
ae20: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ae30: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a  L_VFS_POINTER]].
ae40: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
ae50: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
ae60: 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20  R] opcode finds 
ae70: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
ae80: 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56   top-level.** [V
ae90: 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20  FSes] currently 
aea0: 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61  in use.  ^(The a
aeb0: 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20  rgument X in.** 
aec0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
aed0: 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46  trol(db,SQLITE_F
aee0: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
aef0: 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f  ,X) must be.** o
af00: 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33  f type "[sqlite3
af10: 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73  _vfs] **".  This
af20: 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65   opcodes will se
af30: 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69  t *X.** to a poi
af40: 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d  nter to the top-
af50: 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20  level VFS.)^.** 
af60: 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72 65 20  ^When there are 
af70: 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69  multiple VFS shi
af80: 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c  ms in the stack,
af90: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e   this opcode fin
afa0: 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d  ds the.** upper-
afb0: 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a  most shim only..
afc0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
afd0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
afe0: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61  ].** ^Whenever a
aff0: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
b000: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61  ent is parsed, a
b010: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  n [SQLITE_FCNTL_
b020: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65  PRAGMA] .** file
b030: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74   control is sent
b040: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71   to the open [sq
b050: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
b060: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ct corresponding
b070: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62  .** to the datab
b080: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63  ase file to whic
b090: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61  h the pragma sta
b0a0: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e  tement refers. ^
b0b0: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  The argument.** 
b0c0: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  to the [SQLITE_F
b0d0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
b0e0: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20  e control is an 
b0f0: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e  array of.** poin
b100: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
b110: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63  (char**) in whic
b120: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65  h the second ele
b130: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61  ment of the arra
b140: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  y.** is the name
b150: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61   of the pragma a
b160: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65  nd the third ele
b170: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75  ment is the argu
b180: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70  ment to the.** p
b190: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66  ragma or NULL if
b1a0: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20   the pragma has 
b1b0: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  no argument.  ^T
b1c0: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  he handler for a
b1d0: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  n.** [SQLITE_FCN
b1e0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
b1f0: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69  control can opti
b200: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20  onally make the 
b210: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a  first element.**
b220: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61   of the char** a
b230: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f  rgument point to
b240: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e   a string obtain
b250: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
b260: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f  _mprintf()].** o
b270: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
b280: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67   and that string
b290: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
b2a0: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70   result of the p
b2b0: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20  ragma or.** the 
b2c0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66  error message if
b2d0: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c   the pragma fail
b2e0: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  s. ^If the.** [S
b2f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b300: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
b310: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
b320: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e  _NOTFOUND], then
b330: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41   normal .** [PRA
b340: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20  GMA] processing 
b350: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20  continues.  ^If 
b360: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
b370: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
b380: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
b390: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
b3a0: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61  hen the parser a
b3b0: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
b3c0: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c  ** VFS has handl
b3d0: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74  ed the PRAGMA it
b3e0: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72  self and the par
b3f0: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20  ser generates a 
b400: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65  no-op.** prepare
b410: 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72  d statement if r
b420: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20  esult string is 
b430: 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65  NULL, or that re
b440: 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20  turns a copy.** 
b450: 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 74  of the result st
b460: 72 69 6e 67 20 69 66 20 74 68 65 20 73 74 72 69  ring if the stri
b470: 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a  ng is non-NULL..
b480: 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
b490: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
b4a0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
b4b0: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73  turns.** any res
b4c0: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74  ult code other t
b4d0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  han [SQLITE_OK] 
b4e0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  or [SQLITE_NOTFO
b4f0: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  UND], that means
b500: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53  .** that the VFS
b510: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20   encountered an 
b520: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64  error while hand
b530: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  ling the [PRAGMA
b540: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  ] and the.** com
b550: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  pilation of the 
b560: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74  PRAGMA fails wit
b570: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68  h an error.  ^Th
b580: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b590: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
b5a0: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61  control occurs a
b5b0: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  t the beginning 
b5c0: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  of pragma statem
b5d0: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64  ent analysis and
b5e0: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c   so.** it is abl
b5f0: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75  e to override bu
b600: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20  ilt-in [PRAGMA] 
b610: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
b620: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b630: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
b640: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
b650: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
b660: 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f  DLER].** file-co
b670: 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76  ntrol may be inv
b680: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f  oked by SQLite o
b690: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
b6a0: 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68  ile handle.** sh
b6b0: 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69  ortly after it i
b6c0: 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65  s opened in orde
b6d0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63  r to provide a c
b6e0: 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61  ustom VFS with a
b6f0: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20  ccess.** to the 
b700: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79  connections busy
b710: 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
b720: 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  k. The argument 
b730: 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  is of type (void
b740: 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72   **).** - an arr
b750: 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20  ay of two (void 
b760: 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66  *) values. The f
b770: 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63  irst (void *) ac
b780: 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a  tually points.**
b790: 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
b7a0: 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28  f type (int (*)(
b7b0: 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64  void *)). In ord
b7c0: 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  er to invoke the
b7d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
b7e0: 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68  busy-handler, th
b7f0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  is function shou
b800: 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ld be invoked wi
b810: 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76  th the second (v
b820: 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65  oid *) in.** the
b830: 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e   array as the on
b840: 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20  ly argument. If 
b850: 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  it returns non-z
b860: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70  ero, then the op
b870: 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  eration.** shoul
b880: 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66  d be retried. If
b890: 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f   it returns zero
b8a0: 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53  , the custom VFS
b8b0: 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20   should abandon 
b8c0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f  the.** current o
b8d0: 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  peration..**.** 
b8e0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b8f0: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
b900: 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f  ].** ^Applicatio
b910: 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65  n can invoke the
b920: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
b930: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c  EMPFILENAME] fil
b940: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20  e-control.** to 
b950: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65  have SQLite gene
b960: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72  rate a.** tempor
b970: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69  ary filename usi
b980: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
b990: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f  rithm that is fo
b9a0: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61  llowed to genera
b9b0: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
b9c0: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45  filenames for TE
b9d0: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74  MP tables and ot
b9e0: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65  her internal use
b9f0: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d  s.  The.** argum
ba00: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ent should be a 
ba10: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c  char** which wil
ba20: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68  l be filled with
ba30: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
ba40: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
ba50: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
ba60: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
ba70: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c  oc()].  The call
ba80: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76  er should.** inv
ba90: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
baa0: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75  e()] on the resu
bab0: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65  lt to avoid a me
bac0: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a  mory leak..**.**
bad0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
bae0: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  NTL_MMAP_SIZE]].
baf0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
bb00: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
bb10: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
bb20: 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72  used to query or
bb30: 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69   set the.** maxi
bb40: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
bb50: 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65  tes that will be
bb60: 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79   used for memory
bb70: 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20  -mapped I/O..** 
bb80: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
bb90: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
bba0: 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c  alue of type sql
bbb0: 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a  ite3_int64 that.
bbc0: 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72  ** is an advisor
bbd0: 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  y maximum number
bbe0: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
bbf0: 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20   file to memory 
bc00: 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69  map.  The.** poi
bc10: 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74  nter is overwrit
bc20: 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64  ten with the old
bc30: 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d   value.  The lim
bc40: 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  it is not change
bc50: 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75  d if.** the valu
bc60: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69  e originally poi
bc70: 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74  nted to is negat
bc80: 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ive, and so the 
bc90: 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a  current limit .*
bca0: 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64  * can be queried
bcb0: 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61   by passing in a
bcc0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
bcd0: 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20  gative number.  
bce0: 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  This.** file-con
bcf0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74  trol is used int
bd00: 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65  ernally to imple
bd10: 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61  ment [PRAGMA mma
bd20: 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  p_size]..**.** <
bd30: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
bd40: 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65  L_TRACE]].** The
bd50: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
bd60: 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  RACE] file contr
bd70: 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69  ol provides advi
bd80: 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  sory information
bd90: 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61  .** to the VFS a
bda0: 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69  bout what the hi
bdb0: 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74  gher layers of t
bdc0: 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  he SQLite stack 
bdd0: 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68  are doing..** Th
bde0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
bdf0: 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20  is used by some 
be00: 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61  VFS activity tra
be10: 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a  cing [shims]..**
be20: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
be30: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
be40: 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68  ed string.  High
be50: 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65  er layers in the
be60: 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b  .** SQLite stack
be70: 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e   may generate in
be80: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20  stances of this 
be90: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a  file control if.
bea0: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  ** the [SQLITE_U
beb0: 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20  SE_FCNTL_TRACE] 
bec0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
bed0: 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
bee0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
bef0: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
bf00: 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ED]].** The [SQL
bf10: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
bf20: 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  VED] file contro
bf30: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73  l interprets its
bf40: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a   argument as a.*
bf50: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
bf60: 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77  integer and it w
bf70: 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20  rites a boolean 
bf80: 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
bf90: 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f  r depending.** o
bfa0: 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  n whether or not
bfb0: 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65   the file has be
bfc0: 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65  en renamed, move
bfd0: 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69  d, or deleted si
bfe0: 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69  nce it.** was fi
bff0: 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a  rst opened..**.*
c000: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c010: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
c020: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  ANDLE]].** The [
c030: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c040: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f  32_GET_HANDLE] o
c050: 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65  pcode can be use
c060: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a  d to obtain the.
c070: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61  ** underlying na
c080: 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65  tive file handle
c090: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
c0a0: 20 61 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20   a file handle. 
c0b0: 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f   This file.** co
c0c0: 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73  ntrol interprets
c0d0: 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73   its argument as
c0e0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
c0f0: 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64  native file hand
c100: 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73  le and.** writes
c110: 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 76   the resulting v
c120: 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a  alue there..**.*
c130: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c140: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
c150: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  ANDLE]].** The [
c160: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c170: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f  32_SET_HANDLE] o
c180: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
c190: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
c1a0: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
c1b0: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
c1c0: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73  trol method to s
c1d0: 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e  wap the file han
c1e0: 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65  dle with the one
c1f0: 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
c200: 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  y the pArg argum
c210: 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62  ent.  This capab
c220: 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75  ility is used du
c230: 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20  ring testing.** 
c240: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
c250: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
c260: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20  hen SQLITE_TEST 
c270: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  is defined..**.*
c280: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c290: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d  CNTL_WAL_BLOCK]]
c2a0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
c2b0: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d  FCNTL_WAL_BLOCK]
c2c0: 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20   is a signal to 
c2d0: 74 68 65 20 56 46 53 20 6c 61 79 65 72 20 74 68  the VFS layer th
c2e0: 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62  at it might.** b
c2f0: 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74  e advantageous t
c300: 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e  o block on the n
c310: 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20  ext WAL lock if 
c320: 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20  the lock is not 
c330: 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61  immediately.** a
c340: 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57  vailable.  The W
c350: 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73 73  AL subsystem iss
c360: 75 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20  ues this signal 
c370: 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63  during rare.** c
c380: 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20  ircumstances in 
c390: 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61 20 70  order to fix a p
c3a0: 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f  roblem with prio
c3b0: 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a  rity inversion..
c3c0: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
c3d0: 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f  should <em>not</
c3e0: 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c  em> use this fil
c3f0: 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a  e-control..**.**
c400: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c410: 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20  NTL_ZIPVFS]].** 
c420: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c430: 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65  L_ZIPVFS] opcode
c440: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
c450: 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20  by zipvfs only. 
c460: 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53  All other.** VFS
c470: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53   should return S
c480: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66  QLITE_NOTFOUND f
c490: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a  or this opcode..
c4a0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c4b0: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a  TE_FCNTL_RBU]].*
c4c0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c4d0: 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20  NTL_RBU] opcode 
c4e0: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  is implemented b
c4f0: 79 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  y the special VF
c500: 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65  S used by.** the
c510: 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f   RBU extension o
c520: 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  nly.  All other 
c530: 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72  VFS should retur
c540: 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e  n SQLITE_NOTFOUN
c550: 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70  D for.** this op
c560: 63 6f 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  code.  .**.** <l
c570: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c580: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52  _BEGIN_ATOMIC_WR
c590: 49 54 45 5d 5d 0a 2a 2a 20 49 66 20 74 68 65 20  ITE]].** If the 
c5a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
c5b0: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
c5c0: 5d 20 6f 70 63 6f 64 65 20 72 65 74 75 72 6e 73  ] opcode returns
c5d0: 20 53 51 4c 49 54 45 5f 4f 4b 2c 20 74 68 65 6e   SQLITE_OK, then
c5e0: 0a 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73  .** the file des
c5f0: 63 72 69 70 74 6f 72 20 69 73 20 70 6c 61 63 65  criptor is place
c600: 64 20 69 6e 20 22 62 61 74 63 68 20 77 72 69 74  d in "batch writ
c610: 65 20 6d 6f 64 65 22 2c 20 77 68 69 63 68 0a 2a  e mode", which.*
c620: 2a 20 6d 65 61 6e 73 20 61 6c 6c 20 73 75 62 73  * means all subs
c630: 65 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65  equent write ope
c640: 72 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 20  rations will be 
c650: 64 65 66 65 72 72 65 64 20 61 6e 64 20 64 6f 6e  deferred and don
c660: 65 0a 2a 2a 20 61 74 6f 6d 69 63 61 6c 6c 79 20  e.** atomically 
c670: 61 74 20 74 68 65 20 6e 65 78 74 20 5b 53 51 4c  at the next [SQL
c680: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
c690: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 20  _ATOMIC_WRITE]. 
c6a0: 20 53 79 73 74 65 6d 73 0a 2a 2a 20 74 68 61 74   Systems.** that
c6b0: 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20   do not support 
c6c0: 62 61 74 63 68 20 61 74 6f 6d 69 63 20 77 72 69  batch atomic wri
c6d0: 74 65 73 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  tes will return 
c6e0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 2e  SQLITE_NOTFOUND.
c6f0: 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77 69 6e 67 20 61  .** ^Following a
c700: 20 73 75 63 63 65 73 73 66 75 6c 20 53 51 4c 49   successful SQLI
c710: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
c720: 54 4f 4d 49 43 5f 57 52 49 54 45 20 61 6e 64 20  TOMIC_WRITE and 
c730: 70 72 69 6f 72 20 74 6f 0a 2a 2a 20 74 68 65 20  prior to.** the 
c740: 63 6c 6f 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f  closing [SQLITE_
c750: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
c760: 4d 49 43 5f 57 52 49 54 45 5d 20 6f 72 0a 2a 2a  MIC_WRITE] or.**
c770: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52   [SQLITE_FCNTL_R
c780: 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57  OLLBACK_ATOMIC_W
c790: 52 49 54 45 5d 2c 20 53 51 4c 69 74 65 20 77 69  RITE], SQLite wi
c7a0: 6c 6c 20 6d 61 6b 65 0a 2a 2a 20 6e 6f 20 56 46  ll make.** no VF
c7b0: 53 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c  S interface call
c7c0: 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 73  s on the same [s
c7d0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 66 69 6c  qlite3_file] fil
c7e0: 65 20 64 65 73 63 72 69 70 74 6f 72 0a 2a 2a 20  e descriptor.** 
c7f0: 65 78 63 65 70 74 20 66 6f 72 20 63 61 6c 6c 73  except for calls
c800: 20 74 6f 20 74 68 65 20 78 57 72 69 74 65 20 6d   to the xWrite m
c810: 65 74 68 6f 64 20 61 6e 64 20 74 68 65 20 78 46  ethod and the xF
c820: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
c830: 64 0a 2a 2a 20 77 69 74 68 20 5b 53 51 4c 49 54  d.** with [SQLIT
c840: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
c850: 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  T]..**.** <li>[[
c860: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
c870: 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  MIT_ATOMIC_WRITE
c880: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
c890: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41  E_FCNTL_COMMIT_A
c8a0: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63  TOMIC_WRITE] opc
c8b0: 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77  ode causes all w
c8c0: 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  rite.** operatio
c8d0: 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70 72 65  ns since the pre
c8e0: 76 69 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c  vious successful
c8f0: 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51   call to .** [SQ
c900: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e  LITE_FCNTL_BEGIN
c910: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74  _ATOMIC_WRITE] t
c920: 6f 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 61  o be performed a
c930: 74 6f 6d 69 63 61 6c 6c 79 2e 0a 2a 2a 20 54 68  tomically..** Th
c940: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
c950: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
c960: 4f 4b 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  OK] if and only 
c970: 69 66 20 74 68 65 20 77 72 69 74 65 73 20 77 65  if the writes we
c980: 72 65 0a 2a 2a 20 61 6c 6c 20 70 65 72 66 6f 72  re.** all perfor
c990: 6d 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79  med successfully
c9a0: 20 61 6e 64 20 68 61 76 65 20 62 65 65 6e 20 63   and have been c
c9b0: 6f 6d 6d 69 74 74 65 64 20 74 6f 20 70 65 72 73  ommitted to pers
c9c0: 69 73 74 65 6e 74 20 73 74 6f 72 61 67 65 2e 0a  istent storage..
c9d0: 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
c9e0: 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
c9f0: 20 69 74 20 69 73 20 73 75 63 63 65 73 73 66 75   it is successfu
ca00: 6c 2c 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  l, this file con
ca10: 74 72 6f 6c 20 74 61 6b 65 73 0a 2a 2a 20 74 68  trol takes.** th
ca20: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  e file descripto
ca30: 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77  r out of batch w
ca40: 72 69 74 65 20 6d 6f 64 65 20 73 6f 20 74 68 61  rite mode so tha
ca50: 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  t all subsequent
ca60: 0a 2a 2a 20 77 72 69 74 65 20 6f 70 65 72 61 74  .** write operat
ca70: 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e  ions are indepen
ca80: 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  dent..** ^SQLite
ca90: 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
caa0: 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ke SQLITE_FCNTL_
cab0: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52  COMMIT_ATOMIC_WR
cac0: 49 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61  ITE without.** a
cad0: 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
cae0: 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54  l call to [SQLIT
caf0: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54  E_FCNTL_BEGIN_AT
cb00: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a  OMIC_WRITE]..**.
cb10: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
cb20: 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41  FCNTL_ROLLBACK_A
cb30: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a  TOMIC_WRITE]].**
cb40: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
cb50: 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  TL_ROLLBACK_ATOM
cb60: 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  IC_WRITE] opcode
cb70: 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74   causes all writ
cb80: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20  e.** operations 
cb90: 73 69 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f  since the previo
cba0: 75 73 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  us successful ca
cbb0: 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54  ll to .** [SQLIT
cbc0: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54  E_FCNTL_BEGIN_AT
cbd0: 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62  OMIC_WRITE] to b
cbe0: 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  e rolled back..*
cbf0: 2a 20 5e 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  * ^This file con
cc00: 74 72 6f 6c 20 74 61 6b 65 73 20 74 68 65 20 66  trol takes the f
cc10: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20 6f  ile descriptor o
cc20: 75 74 20 6f 66 20 62 61 74 63 68 20 77 72 69 74  ut of batch writ
cc30: 65 20 6d 6f 64 65 0a 2a 2a 20 73 6f 20 74 68 61  e mode.** so tha
cc40: 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  t all subsequent
cc50: 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e   write operation
cc60: 73 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65 6e  s are independen
cc70: 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  t..** ^SQLite wi
cc80: 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
cc90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c  SQLITE_FCNTL_ROL
cca0: 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49  LBACK_ATOMIC_WRI
ccb0: 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20  TE without.** a 
ccc0: 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
ccd0: 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45   call to [SQLITE
cce0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
ccf0: 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 20 3c  MIC_WRITE]..** <
cd00: 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /ul>.*/.#define 
cd10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
cd20: 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20  KSTATE          
cd30: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
cd40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f  QLITE_FCNTL_GET_
cd50: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
cd60: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
cd70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c  LITE_FCNTL_SET_L
cd80: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
cd90: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
cda0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45  ITE_FCNTL_LAST_E
cdb0: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
cdc0: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
cdd0: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
cde0: 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NT              
cdf0: 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
ce00: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
ce10: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
ce20: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
ce30: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
ce40: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37  TER            7
ce50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ce60: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
ce70: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a  ED            8.
ce80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
ce90: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
cea0: 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23  TRY          9.#
ceb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
cec0: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20  NTL_PERSIST_WAL 
ced0: 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
cee0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
cef0: 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  TL_OVERWRITE    
cf00: 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65            11.#de
cf10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
cf20: 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20  L_VFSNAME       
cf30: 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66           12.#def
cf40: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
cf50: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
cf60: 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69  RITE    13.#defi
cf70: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
cf80: 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
cf90: 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e         14.#defin
cfa0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  e SQLITE_FCNTL_B
cfb0: 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20  USYHANDLER      
cfc0: 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65        15.#define
cfd0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45   SQLITE_FCNTL_TE
cfe0: 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20  MPFILENAME      
cff0: 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20       16.#define 
d000: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
d010: 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  P_SIZE          
d020: 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53      18.#define S
d030: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43  QLITE_FCNTL_TRAC
d040: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
d050: 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51     19.#define SQ
d060: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
d070: 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20 20  OVED            
d080: 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    20.#define SQL
d090: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20  ITE_FCNTL_SYNC  
d0a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d0b0: 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   21.#define SQLI
d0c0: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
d0d0: 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20 20  PHASETWO        
d0e0: 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  22.#define SQLIT
d0f0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45  E_FCNTL_WIN32_SE
d100: 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32  T_HANDLE       2
d110: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
d120: 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b  _FCNTL_WAL_BLOCK
d130: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
d140: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d150: 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 20  FCNTL_ZIPVFS    
d160: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 0a               25.
d170: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d180: 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20 20  CNTL_RBU        
d190: 20 20 20 20 20 20 20 20 20 20 20 20 32 36 0a 23              26.#
d1a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d1b0: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20  NTL_VFS_POINTER 
d1c0: 20 20 20 20 20 20 20 20 20 20 20 32 37 0a 23 64             27.#d
d1d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d1e0: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
d1f0: 45 52 20 20 20 20 20 20 20 20 32 38 0a 23 64 65  ER        28.#de
d200: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d210: 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44  L_WIN32_GET_HAND
d220: 4c 45 20 20 20 20 20 20 20 32 39 0a 23 64 65 66  LE       29.#def
d230: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d240: 5f 50 44 42 20 20 20 20 20 20 20 20 20 20 20 20  _PDB            
d250: 20 20 20 20 20 20 20 20 33 30 0a 23 64 65 66 69          30.#defi
d260: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d270: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49  BEGIN_ATOMIC_WRI
d280: 54 45 20 20 20 20 20 33 31 0a 23 64 65 66 69 6e  TE     31.#defin
d290: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
d2a0: 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49  OMMIT_ATOMIC_WRI
d2b0: 54 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65  TE    32.#define
d2c0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f   SQLITE_FCNTL_RO
d2d0: 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52  LLBACK_ATOMIC_WR
d2e0: 49 54 45 20 20 33 33 0a 0a 2f 2a 20 64 65 70 72  ITE  33../* depr
d2f0: 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a  ecated names */.
d300: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
d310: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
d320: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
d330: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
d340: 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c  FILE.#define SQL
d350: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
d360: 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54  YFILE      SQLIT
d370: 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b  E_FCNTL_SET_LOCK
d380: 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e  PROXYFILE.#defin
d390: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
d3a0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
d3b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53  SQLITE_FCNTL_LAS
d3c0: 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20  T_ERRNO.../*.** 
d3d0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
d3e0: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
d3f0: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
d400: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
d410: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
d420: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
d430: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
d440: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
d450: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
d460: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
d470: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
d480: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
d490: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
d4a0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
d4b0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
d4c0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
d4d0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
d4e0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
d4f0: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
d500: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
d510: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
d520: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
d530: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
d540: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
d550: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d560: 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73 69  Loadable Extensi
d570: 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41  on Thunk.**.** A
d580: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
d590: 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f 61  opaque sqlite3_a
d5a0: 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 75  pi_routines stru
d5b0: 63 74 75 72 65 20 69 73 20 70 61 73 73 65 64 20  cture is passed 
d5c0: 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20  as.** the third 
d5d0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e 74  parameter to ent
d5e0: 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f  ry points of [lo
d5f0: 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e  adable extension
d600: 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 72  s].  This.** str
d610: 75 63 74 75 72 65 20 6d 75 73 74 20 62 65 20 74  ucture must be t
d620: 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64 65  ypedefed in orde
d630: 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  r to work around
d640: 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e   compiler warnin
d650: 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c  gs.** on some pl
d660: 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65  atforms..*/.type
d670: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
d680: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20  e3_api_routines 
d690: 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74  sqlite3_api_rout
d6a0: 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ines;../*.** CAP
d6b0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
d6c0: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
d6d0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
d6e0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
d6f0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
d700: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
d710: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
d720: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
d730: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
d740: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
d750: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
d760: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
d770: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
d780: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
d790: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
d7a0: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
d7b0: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
d7c0: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
d7d0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
d7e0: 56 46 53 20 69 6e 74 65 72 66 61 63 65 20 69 73  VFS interface is
d7f0: 20 73 6f 6d 65 74 69 6d 65 73 20 65 78 74 65 6e   sometimes exten
d800: 64 65 64 20 62 79 20 61 64 64 69 6e 67 20 6e 65  ded by adding ne
d810: 77 20 6d 65 74 68 6f 64 73 20 6f 6e 74 6f 0a 2a  w methods onto.*
d820: 2a 20 74 68 65 20 65 6e 64 2e 20 20 45 61 63 68  * the end.  Each
d830: 20 74 69 6d 65 20 73 75 63 68 20 61 6e 20 65 78   time such an ex
d840: 74 65 6e 73 69 6f 6e 20 6f 63 63 75 72 73 2c 20  tension occurs, 
d850: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
d860: 6c 64 0a 2a 2a 20 69 73 20 69 6e 63 72 65 6d 65  ld.** is increme
d870: 6e 74 65 64 2e 20 20 54 68 65 20 69 56 65 72 73  nted.  The iVers
d880: 69 6f 6e 20 76 61 6c 75 65 20 73 74 61 72 74 65  ion value starte
d890: 64 20 6f 75 74 20 61 73 20 31 20 69 6e 0a 2a 2a  d out as 1 in.**
d8a0: 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e   SQLite [version
d8b0: 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b 64 61 74 65   3.5.0] on [date
d8c0: 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74 68 65 6e 20  of:3.5.0], then 
d8d0: 69 6e 63 72 65 61 73 65 64 20 74 6f 20 32 0a 2a  increased to 2.*
d8e0: 2a 20 77 69 74 68 20 53 51 4c 69 74 65 20 5b 76  * with SQLite [v
d8f0: 65 72 73 69 6f 6e 20 33 2e 37 2e 30 5d 20 6f 6e  ersion 3.7.0] on
d900: 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e 30 5d 2c   [dateof:3.7.0],
d910: 20 61 6e 64 20 74 68 65 6e 20 69 6e 63 72 65 61   and then increa
d920: 73 65 64 0a 2a 2a 20 74 6f 20 33 20 77 69 74 68  sed.** to 3 with
d930: 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e   SQLite [version
d940: 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b 64 61 74 65   3.7.6] on [date
d950: 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20 41 64 64 69  of:3.7.6].  Addi
d960: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a  tional fields.**
d970: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
d980: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
d990: 76 66 73 20 6f 62 6a 65 63 74 20 61 6e 64 20 74  vfs object and t
d9a0: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
d9b0: 65 0a 2a 2a 20 6d 61 79 20 69 6e 63 72 65 61 73  e.** may increas
d9c0: 65 20 61 67 61 69 6e 20 69 6e 20 66 75 74 75 72  e again in futur
d9d0: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
d9e0: 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  Lite..** Note th
d9f0: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65  at the structure
da00: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
da10: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68  e3_vfs object ch
da20: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61  anges in the tra
da30: 6e 73 69 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20  nsition from.** 
da40: 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20  SQLite [version 
da50: 33 2e 35 2e 39 5d 20 74 6f 20 5b 76 65 72 73 69  3.5.9] to [versi
da60: 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e 20 5b 64 61  on 3.6.0] on [da
da70: 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a 2a 2a 20 61  teof:3.6.0].** a
da80: 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73  nd yet the iVers
da90: 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f  ion field was no
daa0: 74 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  t modified..**.*
dab0: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
dac0: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
dad0: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
dae0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
daf0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
db00: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
db10: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
db20: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
db30: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
db40: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
db50: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
db60: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  d sqlite3_vfs ob
db70: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f  jects are kept o
db80: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
db90: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
dba0: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
dbb0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
dbc0: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
dbd0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
dbe0: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
dbf0: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
dc00: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
dc10: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
dc20: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
dc30: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
dc40: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
dc50: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20  ches the list.  
dc60: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c  Neither the appl
dc70: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72  ication code nor
dc80: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c   the VFS.** impl
dc90: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
dca0: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20  d use the pNext 
dcb0: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
dcc0: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
dcd0: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
dce0: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
dcf0: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  vfs.** structure
dd00: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
dd10: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
dd20: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
dd30: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
dd40: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
dd50: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
dd60: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
dd70: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
dd80: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
dd90: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
dda0: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
ddb0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
ddc0: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
ddd0: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
dde0: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
ddf0: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
de00: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
de10: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
de20: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
de30: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
de40: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
de50: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
de60: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
de70: 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74  Open]].** ^SQLit
de80: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
de90: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  t the zFilename 
dea0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
deb0: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  en.** is either 
dec0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
ded0: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  r string obtaine
dee0: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50  d.** from xFullP
def0: 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61  athname() with a
df00: 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69  n optional suffi
df10: 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  x added..** ^If 
df20: 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65  a suffix is adde
df30: 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61  d to the zFilena
df40: 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74  me parameter, it
df50: 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74   will.** consist
df60: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22   of a single "-"
df70: 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f   character follo
df80: 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74  wed by no more t
df90: 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e  han.** 11 alphan
dfa0: 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d  umeric and/or "-
dfb0: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
dfc0: 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72   ^SQLite further
dfd0: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
dfe0: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
dff0: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
e000: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
e010: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
e020: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20  called. Because 
e030: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
e040: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65  sentence,.** the
e050: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
e060: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65  can safely store
e070: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
e080: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
e090: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
e0a0: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
e0b0: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
e0c0: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  on..** If the zF
e0d0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
e0e0: 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20  r to xOpen is a 
e0f0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
e100: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20  n xOpen.** must 
e110: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74  invent its own t
e120: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f  emporary name fo
e130: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68  r the file.  ^Wh
e140: 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78  enever the .** x
e150: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
e160: 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69  er is NULL it wi
e170: 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63  ll also be the c
e180: 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ase that the.** 
e190: 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
e1a0: 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51  will include [SQ
e1b0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
e1c0: 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20  ONCLOSE]..**.** 
e1d0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
e1e0: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e  nt to xOpen() in
e1f0: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20  cludes all bits 
e200: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c  set in.** the fl
e210: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
e220: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
e230: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c  ()].  Or if [sql
e240: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
e250: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
e260: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74  16()] is used, t
e270: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64  hen flags includ
e280: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b  es at least.** [
e290: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
e2a0: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
e2b0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a  _OPEN_CREATE]. .
e2c0: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70  ** If xOpen() op
e2d0: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d  ens a file read-
e2e0: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74  only then it set
e2f0: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a  s *pOutFlags to.
e300: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ** include [SQLI
e310: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
e320: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  ].  Other bits i
e330: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
e340: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e   be set..**.** ^
e350: 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73  (SQLite will als
e360: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
e370: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
e380: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
e390: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
e3a0: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
e3b0: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
e3c0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
e3d0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
e3e0: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
e3f0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
e400: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
e410: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
e420: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
e430: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
e440: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
e450: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
e460: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
e470: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
e480: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
e490: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
e4a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
e4b0: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
e4c0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
e4d0: 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29  N_WAL].** </ul>)
e4e0: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  ^.**.** The file
e4f0: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
e500: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
e510: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
e520: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
e530: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
e540: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
e550: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
e560: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
e570: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
e580: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
e590: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
e5a0: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
e5b0: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
e5c0: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
e5d0: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
e5e0: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
e5f0: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
e600: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
e610: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
e620: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
e630: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
e640: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
e650: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
e660: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
e670: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
e680: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
e690: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
e6a0: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
e6b0: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
e6c0: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
e6d0: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
e6e0: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
e6f0: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
e700: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
e710: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
e720: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
e730: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
e740: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
e750: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
e760: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
e770: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
e780: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
e790: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
e7a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
e7b0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
e7c0: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
e7d0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
e7e0: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
e7f0: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68   is closed.  ^Th
e800: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
e810: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
e820: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72   will be set for
e830: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20   TEMP databases 
e840: 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61  and their journa
e850: 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a  ls, transient.**
e860: 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20   databases, and 
e870: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a  subjournals..**.
e880: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
e890: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20  OPEN_EXCLUSIVE] 
e8a0: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75  flag is always u
e8b0: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69  sed in conjuncti
e8c0: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
e8d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
e8e0: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20  TE] flag, which 
e8f0: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c  are both directl
e900: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74  y.** analogous t
e910: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64  o the O_EXCL and
e920: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f   O_CREAT flags o
e930: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e  f the POSIX open
e940: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20  ().** API.  The 
e950: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
e960: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e  USIVE flag, when
e970: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65   paired with the
e980: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e   .** SQLITE_OPEN
e990: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64  _CREATE, is used
e9a0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
e9b0: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c  t file should al
e9c0: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74  ways.** be creat
e9d0: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20  ed, and that it 
e9e0: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69  is an error if i
e9f0: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73  t already exists
ea00: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f  ..** It is <i>no
ea10: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e  t</i> used to in
ea20: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20  dicate the file 
ea30: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
ea40: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69   .** for exclusi
ea50: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a  ve access..**.**
ea60: 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46   ^At least szOsF
ea70: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  ile bytes of mem
ea80: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  ory are allocate
ea90: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74  d by SQLite.** t
eaa0: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c  o hold the  [sql
eab0: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
eac0: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
ead0: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
eae0: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20  ment to xOpen.  
eaf0: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
eb00: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74   does not have t
eb10: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68  o.** allocate th
eb20: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20  e structure; it 
eb30: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c  should just fill
eb40: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68   it in.  Note th
eb50: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20  at.** the xOpen 
eb60: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20  method must set 
eb70: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
eb80: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74  .pMethods to eit
eb90: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b  her.** a valid [
eba0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
ebb0: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f  ds] object or to
ebc0: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75   NULL.  xOpen mu
ebd0: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76  st do.** this ev
ebe0: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66  en if the open f
ebf0: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78  ails.  SQLite ex
ec00: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73  pects that the s
ec10: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
ec20: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20  hods.** element 
ec30: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66  will be valid af
ec40: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e  ter xOpen return
ec50: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  s regardless of 
ec60: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f  the success.** o
ec70: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65  r failure of the
ec80: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a   xOpen call..**.
ec90: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
eca0: 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54  .xAccess]].** ^T
ecb0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
ecc0: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
ecd0: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
ece0: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
ecf0: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
ed00: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
ed10: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
ed20: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
ed30: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
ed40: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
ed50: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
ed60: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
ed70: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
ed80: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
ed90: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
eda0: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
edb0: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
edc0: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
edd0: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
ede0: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
edf0: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
ee00: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
ee10: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
ee20: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
ee30: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63  hname.  The exac
ee40: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
ee50: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
ee60: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
ee70: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
ee80: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49  both  methods. I
ee90: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
eea0: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61  fer.** is not la
eeb0: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c  rge enough, [SQL
eec0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68  ITE_CANTOPEN] sh
eed0: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
eee0: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a  . Since this is.
eef0: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  ** handled as a 
ef00: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
ef10: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65  QLite, vfs imple
ef20: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
ef30: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f  d endeavor.** to
ef40: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
ef50: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e   setting mxPathn
ef60: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69  ame to a suffici
ef70: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75  ently large valu
ef80: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61  e..**.** The xRa
ef90: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
efa0: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69  ep(), xCurrentTi
efb0: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  me(), and xCurre
efc0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a  ntTimeInt64().**
efd0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
efe0: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70  not strictly a p
eff0: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73  art of the files
f000: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20  ystem, but they 
f010: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20  are.** included 
f020: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63  in the VFS struc
f030: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74  ture for complet
f040: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52  eness..** The xR
f050: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63  andomness() func
f060: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f  tion attempts to
f070: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62   return nBytes b
f080: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d  ytes.** of good-
f090: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
f0a0: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54  ss into zOut.  T
f0b0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
f0c0: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c  is.** the actual
f0d0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
f0e0: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f   of randomness o
f0f0: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  btained..** The 
f100: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
f110: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69  causes the calli
f120: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
f130: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
f140: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
f150: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
f160: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72  ven.  ^The xCurr
f170: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74  entTime().** met
f180: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75  hod returns a Ju
f190: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20  lian Day Number 
f1a0: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
f1b0: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73  date and time as
f1c0: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70  .** a floating p
f1d0: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e  oint value..** ^
f1e0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
f1f0: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72  Int64() method r
f200: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e  eturns, as an in
f210: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61  teger, the Julia
f220: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20  n.** Day Number 
f230: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36  multiplied by 86
f240: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
f250: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
f260: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
f270: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
f280: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
f290: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
f2a0: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
f2b0: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
f2c0: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
f2d0: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
f2e0: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
f2f0: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
f300: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
f310: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
f320: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
f330: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
f340: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
f350: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
f360: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
f370: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
f380: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
f390: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xSetSystemCall()
f3a0: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  , xGetSystemCall
f3b0: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73  (), and xNestSys
f3c0: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66  temCall() interf
f3d0: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
f3e0: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69  used by the SQLi
f3f0: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20  te core.  These 
f400: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61  optional interfa
f410: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
f420: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65  .** by some VFSe
f430: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20  s to facilitate 
f440: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56  testing of the V
f450: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72  FS code. By over
f460: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65  riding .** syste
f470: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e  m calls with fun
f480: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73  ctions under its
f490: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74   control, a test
f4a0: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20   program can.** 
f4b0: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20  simulate faults 
f4c0: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74  and error condit
f4d0: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20  ions that would 
f4e0: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66  otherwise be dif
f4f0: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70  ficult.** or imp
f500: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63  ossible to induc
f510: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73  e.  The set of s
f520: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74  ystem calls that
f530: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
f540: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f  en.** varies fro
f550: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f  m one VFS to ano
f560: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f  ther, and from o
f570: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ne version of th
f580: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68  e same VFS to th
f590: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
f5a0: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
f5b0: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  e these interfac
f5c0: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61  es must be prepa
f5d0: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f  red for any.** o
f5e0: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69  r all of these i
f5f0: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20  nterfaces to be 
f600: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69  NULL or for thei
f610: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68  r behavior to ch
f620: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65  ange.** from one
f630: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20   release to the 
f640: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
f650: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74  ons must not att
f660: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a  empt to access.*
f670: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d  * any of these m
f680: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56  ethods if the iV
f690: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46  ersion of the VF
f6a0: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33  S is less than 3
f6b0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
f6c0: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
f6d0: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70  sqlite3_vfs;.typ
f6e0: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
f6f0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
f700: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73  (void);.struct s
f710: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
f720: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
f730: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
f740: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
f750: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33  ber (currently 3
f760: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
f770: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
f780: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
f790: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
f7a0: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
f7b0: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
f7c0: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
f7d0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
f7e0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
f7f0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
f800: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
f810: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
f820: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
f830: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
f840: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
f850: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
f860: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
f870: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
f880: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
f890: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
f8a0: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
f8b0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
f8c0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
f8d0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
f8e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
f8f0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
f900: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
f910: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
f920: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
f930: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
f940: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
f950: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
f960: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
f970: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
f980: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
f990: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
f9a0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
f9b0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
f9c0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
f9d0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
f9e0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
f9f0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
fa00: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
fa10: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
fa20: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
fa30: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
fa40: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
fa50: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
fa60: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
fa70: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
fa80: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
fa90: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
faa0: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
fab0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
fac0: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
fad0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
fae0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
faf0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
fb00: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
fb10: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
fb20: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
fb30: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
fb40: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
fb50: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
fb60: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
fb70: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
fb80: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
fb90: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
fba0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
fbb0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
fbc0: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
fbd0: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
fbe0: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
fbf0: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
fc00: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
fc10: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
fc20: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72   */.  int (*xCur
fc30: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73  rentTimeInt64)(s
fc40: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c  qlite3_vfs*, sql
fc50: 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20  ite3_int64*);.  
fc60: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
fc70: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
fc80: 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20   versions 1 and 
fc90: 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  2 of the sqlite_
fca0: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
fcb0: 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65   Those below are
fcc0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61   for version 3 a
fcd0: 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f  nd greater..  */
fce0: 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73  .  int (*xSetSys
fcf0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
fd00: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
fd10: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
fd20: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a  3_syscall_ptr);.
fd30: 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c    sqlite3_syscal
fd40: 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74  l_ptr (*xGetSyst
fd50: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
fd60: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
fd70: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73   *zName);.  cons
fd80: 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53  t char *(*xNextS
fd90: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
fda0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
fdb0: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f  har *zName);.  /
fdc0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
fdd0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
fde0: 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75  versions 1 throu
fdf0: 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69  gh 3 of the sqli
fe00: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
fe10: 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   ** New fields m
fe20: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
fe30: 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
fe40: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
fe50: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
fe60: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
fe70: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
fe80: 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  . .  */.};../*.*
fe90: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
fea0: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
feb0: 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  s VFS method.**.
fec0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
fed0: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
fee0: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
fef0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
ff00: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
ff10: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
ff20: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
ff30: 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  t.  They determi
ff40: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
ff50: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
ff60: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
ff70: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
ff80: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
ff90: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
ffa0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
ffb0: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
ffc0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
ffd0: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
ffe0: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
fff0: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
10000 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
10010 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
10020 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72  er the named dir
10030 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72  ectory is both r
10040 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
10050 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65  able.** (in othe
10060 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65  r words, if file
10070 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20  s can be added, 
10080 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e  removed, and ren
10090 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74  amed within.** t
100a0 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a  he directory)..*
100b0 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43  * The SQLITE_ACC
100c0 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f  ESS_READWRITE co
100d0 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e  nstant is curren
100e0 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79  tly used only by
100f0 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74   the.** [temp_st
10100 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
10110 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68  agma], though th
10120 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20  is could change 
10130 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
10140 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
10150 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
10160 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
10170 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
10180 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
10190 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
101a0 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51  eadable.  The SQ
101b0 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
101c0 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20   constant is.** 
101d0 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64  currently unused
101e0 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68  , though it migh
101f0 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66  t be used in a f
10200 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
10210 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23  .** SQLite..*/.#
10220 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
10230 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
10240 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10250 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
10260 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20   1   /* Used by 
10270 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72  PRAGMA temp_stor
10280 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23  e_directory */.#
10290 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
102a0 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
102b0 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a     /* Unused */.
102c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
102d0 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
102e0 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68  ShmLock VFS meth
102f0 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
10300 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
10310 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69   define the vari
10320 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72  ous locking oper
10330 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65  ations.** allowe
10340 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63  d by the xShmLoc
10350 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c  k method of [sql
10360 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
10370 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  .  The.** follow
10380 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79  ing are the only
10390 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69   legal combinati
103a0 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20  ons of flags to 
103b0 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20  the.** xShmLock 
103c0 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
103d0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
103e0 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
103f0 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
10400 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
10410 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
10420 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
10430 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
10440 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
10450 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
10460 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
10470 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
10480 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
10490 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
104a0 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20  When unlocking, 
104b0 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20  the same SHARED 
104c0 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61  or EXCLUSIVE fla
104d0 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69  g must be suppli
104e0 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76  ed as.** was giv
104f0 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73  en on the corres
10500 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a  ponding lock.  .
10510 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
10520 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72  ck method can tr
10530 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
10540 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48   unlocked and SH
10550 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65  ARED or.** betwe
10560 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
10570 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63  EXCLUSIVE.  It c
10580 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e  annot transition
10590 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a   between SHARED.
105a0 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ** and EXCLUSIVE
105b0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
105c0 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20  ITE_SHM_UNLOCK  
105d0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
105e0 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20  QLITE_SHM_LOCK  
105f0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
10600 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
10610 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69  ED       4.#defi
10620 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58  ne SQLITE_SHM_EX
10630 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a  CLUSIVE    8../*
10640 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
10650 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69  ximum xShmLock i
10660 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ndex.**.** The x
10670 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
10680 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
10690 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76  thods] may use v
106a0 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
106b0 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65   0 and this uppe
106c0 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22  r bound as its "
106d0 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74  offset" argument
106e0 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
106f0 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  core will never 
10700 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69  attempt to acqui
10710 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a  re or release a.
10720 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20  ** lock outside 
10730 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f  of this range.*/
10740 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10750 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20  SHM_NLOCK       
10760 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   8.../*.** CAPI3
10770 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
10780 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
10790 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
107a0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
107b0 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
107c0 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
107d0 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e  Lite library.  ^
107e0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
107f0 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
10800 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
10810 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
10820 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
10830 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
10840 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73  alize()..** Thes
10850 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
10860 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69  esigned to aid i
10870 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  n process initia
10880 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  lization and.** 
10890 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65  shutdown on embe
108a0 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57  dded systems.  W
108b0 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69  orkstation appli
108c0 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a  cations using.**
108d0 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79   SQLite normally
108e0 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20   do not need to 
108f0 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66  invoke either of
10900 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
10910 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
10920 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10930 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
10940 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
10950 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
10960 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
10970 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
10980 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
10990 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
109a0 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
109b0 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
109c0 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
109d0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
109e0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
109f0 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
10a00 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10a10 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20  n().  ^(Only an 
10a20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a  effective call.*
10a30 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69  * of sqlite3_ini
10a40 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61  tialize() does a
10a50 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ny initializatio
10a60 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  n.  All other ca
10a70 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c  lls.** are harml
10a80 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
10a90 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
10aa0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10ab0 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
10ac0 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
10ad0 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61   the first.** ca
10ae0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
10af0 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74  utdown() since t
10b00 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
10b10 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e  initialize().  ^
10b20 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65  (Only.** an effe
10b30 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
10b40 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10b50 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
10b60 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
10b70 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63  ll other valid c
10b80 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
10b90 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68  shutdown() are h
10ba0 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
10bb0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ^.**.** The sqli
10bc0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10bd0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
10be0 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71  readsafe, but sq
10bf0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10c00 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65  .** is not.  The
10c10 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10c20 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75  n() interface mu
10c30 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  st only be calle
10c40 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67  d from a.** sing
10c50 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20  le thread.  All 
10c60 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
10c70 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74  onnections] must
10c80 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61   be closed and a
10c90 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ll.** other SQLi
10ca0 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73  te resources mus
10cb0 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  t be deallocated
10cc0 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69   prior to invoki
10cd0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68  ng.** sqlite3_sh
10ce0 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  utdown()..**.** 
10cf0 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
10d00 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69  gs, ^sqlite3_ini
10d10 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69  tialize() will i
10d20 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
10d30 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
10d40 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33  ilarly, ^sqlite3
10d50 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77  _shutdown().** w
10d60 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ill invoke sqlit
10d70 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
10d80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
10d90 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
10da0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
10db0 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
10dc0 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20  ess..** ^If for 
10dd0 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c  some reason, sql
10de0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10df0 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69  ) is unable to i
10e00 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65  nitialize.** the
10e10 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70   library (perhap
10e20 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  s it is unable t
10e30 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65  o allocate a nee
10e40 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63  ded resource suc
10e50 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29  h.** as a mutex)
10e60 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b   it returns an [
10e70 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
10e80 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
10e90 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  K]..**.** ^The s
10ea0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10eb0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
10ec0 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
10ed0 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
10ee0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
10ef0 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
10f00 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
10f10 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
10f20 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
10f30 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10f40 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
10f50 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
10f60 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
10f70 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
10f80 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
10f90 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
10fa0 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
10fb0 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
10fc0 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
10fd0 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
10fe0 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
10ff0 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
11000 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e  d.** already.  ^
11010 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
11020 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11030 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
11040 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a  OMIT_AUTOINIT].*
11050 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
11060 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
11070 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
11080 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
11090 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
110a0 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
110b0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
110c0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
110d0 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
110e0 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
110f0 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
11100 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
11110 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
11120 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
11130 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
11140 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
11150 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
11160 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11170 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
11180 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
11190 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
111a0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
111b0 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
111c0 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
111d0 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
111e0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
111f0 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
11200 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
11210 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11220 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  ith [SQLITE_OMIT
11230 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74  _AUTOINIT] might
11240 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
11250 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
11260 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
11270 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
11280 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
11290 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
112a0 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
112b0 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
112c0 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
112d0 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
112e0 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
112f0 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
11300 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
11310 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
11320 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
11330 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
11340 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
11350 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
11360 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
11370 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
11380 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
11390 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
113a0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
113b0 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
113c0 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
113d0 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
113e0 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
113f0 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
11400 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
11410 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
11420 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11430 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
11440 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
11450 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
11460 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
11470 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
11480 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
11490 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
114a0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
114b0 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
114c0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
114d0 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
114e0 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
114f0 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
11500 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
11510 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
11520 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
11530 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11540 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
11550 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
11560 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
11570 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
11580 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
11590 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
115a0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
115b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
115c0 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
115d0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
115e0 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
115f0 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64  d for Unix, Wind
11600 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a  ows, or OS/2..**
11610 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75   When [custom bu
11620 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72  ilds | built for
11630 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
11640 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20  ].** (using the 
11650 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52  [SQLITE_OS_OTHER
11660 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =1] compile-time
11670 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20  .** option) the 
11680 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
11690 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62   supply a suitab
116a0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
116b0 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  n for.** sqlite3
116c0 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
116d0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
116e0 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    An application
116f0 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70  -supplied.** imp
11700 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
11710 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
11720 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
11730 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74  nd().** must ret
11740 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
11750 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
11760 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
11770 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
11780 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73  ailure..*/.int s
11790 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
117a0 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  e(void);.int sql
117b0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f  ite3_shutdown(vo
117c0 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
117d0 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
117e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  int sqlite3_os_e
117f0 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  nd(void);../*.**
11800 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
11810 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74  guring The SQLit
11820 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
11830 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
11840 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
11850 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67  s used to make g
11860 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74  lobal configurat
11870 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
11880 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  o SQLite in orde
11890 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65  r to tune SQLite
118a0 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
118b0 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65   needs of.** the
118c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54   application.  T
118d0 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  he default confi
118e0 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f  guration is reco
118f0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74  mmended for most
11900 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
11910 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75   and so this rou
11920 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20  tine is usually 
11930 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20  not necessary.  
11940 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65  It is.** provide
11950 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72  d to support rar
11960 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77  e applications w
11970 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64  ith unusual need
11980 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20  s..**.** <b>The 
11990 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
119a0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
119b0 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68  t threadsafe. Th
119c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
119d0 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61   must ensure tha
119e0 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
119f0 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
11a00 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
11a10 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
11a20 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
11a30 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c  g() is running.<
11a40 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  /b>.**.** The sq
11a50 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
11a60 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20  nterface.** may 
11a70 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
11a80 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
11a90 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
11aa0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
11ab0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
11ac0 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
11ad0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
11ae0 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49  utdown()]..** ^I
11af0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  f sqlite3_config
11b00 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74  () is called aft
11b10 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  er [sqlite3_init
11b20 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65  ialize()] and be
11b30 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fore.** [sqlite3
11b40 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65  _shutdown()] the
11b50 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  n it will return
11b60 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
11b70 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
11b80 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f  , that ^sqlite3_
11b90 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
11ba0 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
11bb0 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
11bc0 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
11bd0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
11be0 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
11bf0 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
11c00 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
11c10 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
11c20 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
11c30 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74  r.** [configurat
11c40 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74  ion option] that
11c50 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77   determines.** w
11c60 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20  hat property of 
11c70 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20  SQLite is to be 
11c80 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62  configured.  Sub
11c90 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
11ca0 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64  s.** vary depend
11cb0 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66  ing on the [conf
11cc0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11cd0 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
11ce0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
11cf0 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67  * ^When a config
11d00 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
11d10 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63  s set, sqlite3_c
11d20 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20  onfig() returns 
11d30 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20  [SQLITE_OK]..** 
11d40 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69  ^If the option i
11d50 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c  s unknown or SQL
11d60 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
11d70 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a   set the option.
11d80 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  ** then this rou
11d90 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e  tine returns a n
11da0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
11db0 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ode]..*/.int sql
11dc0 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c  ite3_config(int,
11dd0 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
11de0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
11df0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
11e00 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
11e10 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
11e20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
11e30 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
11e40 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
11e50 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
11e60 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
11e70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11e80 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
11e90 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
11ea0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
11eb0 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
11ec0 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
11ed0 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
11ee0 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
11ef0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
11f00 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
11f10 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
11f20 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
11f30 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
11f40 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
11f50 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
11f60 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
11f70 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
11f80 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
11f90 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
11fa0 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
11fb0 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
11fc0 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
11fd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11fe0 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
11ff0 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
12000 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
12010 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
12020 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
12030 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
12040 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
12050 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
12060 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
12070 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
12080 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
12090 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
120a0 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
120b0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
120c0 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
120d0 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
120e0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
120f0 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
12100 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
12110 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
12120 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
12130 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
12140 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
12150 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
12160 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
12170 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
12180 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
12190 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
121a0 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
121b0 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
121c0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
121d0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
121e0 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
121f0 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
12200 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
12210 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
12220 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
12230 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12240 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
12250 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
12260 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
12270 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
12280 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
12290 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
122a0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
122b0 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
122c0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
122d0 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
122e0 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
122f0 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
12300 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
12310 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
12320 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
12330 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
12340 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
12350 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
12360 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
12370 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
12380 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
12390 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
123a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
123b0 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
123c0 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
123d0 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
123e0 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
123f0 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
12400 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
12410 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
12420 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
12430 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
12440 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
12450 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
12460 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
12470 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
12480 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
12490 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
124a0 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
124b0 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
124c0 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
124d0 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
124e0 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
124f0 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
12500 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
12510 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
12520 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
12530 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
12540 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
12550 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
12560 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
12570 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
12580 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
12590 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
125a0 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
125b0 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
125c0 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
125d0 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
125e0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
125f0 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
12600 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
12610 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
12620 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
12630 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
12640 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
12650 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
12660 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
12670 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
12680 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
12690 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
126a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
126b0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
126c0 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
126d0 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
126e0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
126f0 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
12700 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
12710 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
12720 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
12730 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
12740 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
12750 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
12760 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
12770 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
12780 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
12790 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
127a0 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
127b0 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
127c0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
127d0 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
127e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
127f0 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
12800 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
12810 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
12820 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
12830 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
12840 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
12850 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
12860 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
12870 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
12880 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
12890 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
128a0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
128b0 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
128c0 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
128d0 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
128e0 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
128f0 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
12900 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
12910 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
12920 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
12930 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
12940 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
12950 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
12960 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
12970 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
12980 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
12990 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
129a0 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
129b0 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
129c0 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
129d0 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
129e0 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
129f0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
12a00 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
12a10 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
12a20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
12a30 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
12a40 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
12a50 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
12a60 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
12a70 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
12a80 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
12a90 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
12aa0 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
12ab0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
12ac0 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65  ASTER] mutex whe
12ad0 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  n it invokes.** 
12ae0 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
12af0 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d  , so the xInit m
12b00 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62  ethod need not b
12b10 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  e threadsafe.  T
12b20 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20  he.** xShutdown 
12b30 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63  method is only c
12b40 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  alled from [sqli
12b50 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
12b60 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  so it does.** no
12b70 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72  t need to be thr
12b80 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20  eadsafe either. 
12b90 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d   For all other m
12ba0 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a  ethods, SQLite.*
12bb0 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  * holds the [SQL
12bc0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
12bd0 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c  _MEM] mutex as l
12be0 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53  ong as the.** [S
12bf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
12c00 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72  STATUS] configur
12c10 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
12c20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68  turned on (which
12c30 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66  .** it is by def
12c40 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65  ault) and so the
12c50 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74   methods are aut
12c60 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61  omatically seria
12c70 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65  lized..** Howeve
12c80 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f  r, if [SQLITE_CO
12c90 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
12ca0 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  is disabled, the
12cb0 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d  n the other.** m
12cc0 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74  ethods must be t
12cd0 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73  hreadsafe or els
12ce0 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e  e make their own
12cf0 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f   arrangements fo
12d00 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69  r.** serializati
12d10 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
12d20 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
12d30 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20  ke xInit() more 
12d40 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75  than once withou
12d50 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67  t an intervening
12d60 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75  .** call to xShu
12d70 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65  tdown()..*/.type
12d80 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
12d90 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
12da0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12db0 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
12dc0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
12dd0 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
12de0 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
12df0 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
12e00 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
12e10 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
12e20 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
12e30 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
12e40 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
12e50 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
12e60 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
12e70 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
12e80 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
12e90 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
12ea0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
12eb0 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
12ec0 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
12ed0 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
12ee0 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
12ef0 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
12f00 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
12f10 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
12f20 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
12f30 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
12f40 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
12f50 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
12f60 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
12f70 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
12f80 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
12f90 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
12fa0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
12fb0 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
12fc0 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
12fd0 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
12fe0 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
12ff0 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
13000 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
13010 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
13020 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45  on Options.** KE
13030 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75  YWORDS: {configu
13040 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a  ration option}.*
13050 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
13060 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
13070 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
13080 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13090 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
130a0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
130b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
130c0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
130d0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
130e0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
130f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13100 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
13110 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
13120 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
13130 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
13140 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13150 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
13160 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
13170 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
13180 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
13190 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
131a0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
131b0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
131c0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
131d0 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
131e0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
131f0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
13200 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
13210 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
13220 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
13230 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
13240 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13250 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
13260 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
13270 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13280 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d  G_SINGLETHREAD]]
13290 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
132a0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
132b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
132c0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
132d0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
132e0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
132f0 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
13300 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
13310 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
13320 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
13330 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
13340 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
13350 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
13360 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
13370 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
13380 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
13390 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
133a0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
133b0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
133c0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
133d0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
133e0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
133f0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
13400 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
13410 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
13420 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
13430 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
13440 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
13450 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
13460 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
13470 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
13480 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
13490 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
134a0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
134b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
134c0 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
134d0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
134e0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
134f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
13500 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  TITHREAD]] <dt>S
13510 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
13520 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
13530 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
13540 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
13550 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
13560 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
13570 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
13580 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
13590 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
135a0 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
135b0 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
135c0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
135d0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
135e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
135f0 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
13600 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
13610 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
13620 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
13630 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
13640 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
13650 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
13660 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
13670 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
13680 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
13690 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
136a0 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
136b0 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
136c0 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
136d0 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
136e0 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
136f0 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
13700 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
13710 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
13720 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
13730 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
13740 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
13750 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
13760 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
13770 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
13780 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
13790 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
137a0 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
137b0 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
137c0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
137d0 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
137e0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
137f0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
13800 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
13810 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
13820 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
13830 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
13840 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13850 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
13860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
13870 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53  RIALIZED]] <dt>S
13880 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
13890 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
138a0 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
138b0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
138c0 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
138d0 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
138e0 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
138f0 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69  mode] to Seriali
13900 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  zed. In other wo
13910 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e  rds, this option
13920 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
13930 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
13940 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
13950 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
13960 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13970 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
13980 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
13990 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
139a0 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
139b0 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
139c0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
139d0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
139e0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
139f0 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
13a00 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
13a10 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
13a20 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
13a30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
13a40 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
13a50 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
13a60 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
13a70 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
13a80 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
13a90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13aa0 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
13ab0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
13ac0 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
13ad0 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
13ae0 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
13af0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
13b00 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
13b10 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
13b20 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
13b30 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
13b40 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
13b50 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
13b60 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
13b70 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a  set the Serializ
13b80 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
13b90 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
13ba0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
13bb0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
13bc0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
13bd0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
13be0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
13bf0 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72  IALIZED configur
13c00 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
13c10 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13c20 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
13c30 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13c40 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
13c50 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
13c60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
13c70 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
13c80 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
13c90 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61  t which is .** a
13ca0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
13cb0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
13cc0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
13cd0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
13ce0 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
13cf0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
13d00 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
13d10 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
13d20 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f  tion routines to
13d30 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
13d40 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  e of.** the memo
13d50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
13d60 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
13d70 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c  o SQLite.)^ ^SQL
13d80 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73  ite makes.** its
13d90 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
13da0 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74  y of the content
13db0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
13dc0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
13dd0 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72  ructure.** befor
13de0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  e the [sqlite3_c
13df0 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65  onfig()] call re
13e00 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  turns.</dd>.**.*
13e10 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13e20 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  G_GETMALLOC]] <d
13e30 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13e40 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
13e50 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
13e60 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
13e70 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65  LLOC option take
13e80 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
13e90 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
13ea0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
13eb0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
13ec0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
13ed0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
13ee0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
13ef0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
13f00 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
13f10 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
13f20 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
13f30 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13f40 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
13f50 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
13f60 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
13f70 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
13f80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13f90 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
13fa0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
13fb0 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
13fc0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13fd0 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
13fe0 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
13ff0 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
14000 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14010 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41  QLITE_CONFIG_SMA
14020 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  LL_MALLOC]] <dt>
14030 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d  SQLITE_CONFIG_SM
14040 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  ALL_MALLOC</dt>.
14050 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
14060 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c  ITE_CONFIG_SMALL
14070 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74  _MALLOC option t
14080 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
14090 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74 79 70 65 20  ment of.** type 
140a0 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
140b0 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77   as a boolean, w
140c0 68 69 63 68 20 69 66 20 74 72 75 65 20 70 72 6f  hich if true pro
140d0 76 69 64 65 73 20 61 20 68 69 6e 74 20 74 6f 0a  vides a hint to.
140e0 2a 2a 20 53 51 4c 69 74 65 20 74 68 61 74 20 69  ** SQLite that i
140f0 74 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 20 6c  t should avoid l
14100 61 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  arge memory allo
14110 63 61 74 69 6f 6e 73 20 69 66 20 70 6f 73 73 69  cations if possi
14120 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ble..** SQLite w
14130 69 6c 6c 20 72 75 6e 20 66 61 73 74 65 72 20 69  ill run faster i
14140 66 20 69 74 20 69 73 20 66 72 65 65 20 74 6f 20  f it is free to 
14150 6d 61 6b 65 20 6c 61 72 67 65 20 6d 65 6d 6f 72  make large memor
14160 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 0a 2a  y allocations,.*
14170 2a 20 62 75 74 20 73 6f 6d 65 20 61 70 70 6c 69  * but some appli
14180 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 70 72 65  cation might pre
14190 66 65 72 20 74 6f 20 72 75 6e 20 73 6c 6f 77 65  fer to run slowe
141a0 72 20 69 6e 20 65 78 63 68 61 6e 67 65 20 66 6f  r in exchange fo
141b0 72 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  r.** guarantees 
141c0 61 62 6f 75 74 20 6d 65 6d 6f 72 79 20 66 72 61  about memory fra
141d0 67 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20  gmentation that 
141e0 61 72 65 20 70 6f 73 73 69 62 6c 65 20 69 66 20  are possible if 
141f0 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  large.** allocat
14200 69 6f 6e 73 20 61 72 65 20 61 76 6f 69 64 65 64  ions are avoided
14210 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
14220 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e 0a 2a 2a  normally off..**
14230 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14240 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
14250 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c  STATUS]] <dt>SQL
14260 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
14270 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
14280 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
14290 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f  NFIG_MEMSTATUS o
142a0 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67  ption takes sing
142b0 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
142c0 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65  ype int,.** inte
142d0 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
142e0 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
142f0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
14300 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
14310 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  f.** memory allo
14320 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
14330 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79  s. ^(When memory
14340 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
14350 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69  istics are.** di
14360 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c  sabled, the foll
14370 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
14380 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e  erfaces become n
14390 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a  on-operational:.
143a0 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  **   <ul>.**   <
143b0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
143c0 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20  ory_used()].**  
143d0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
143e0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
143f0 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
14400 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
14410 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20  limit64()].**   
14420 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
14430 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  atus64()].**   <
14440 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
14450 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
14460 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
14470 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
14480 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
14490 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
144a0 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
144b0 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
144c0 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
144d0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
144e0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
144f0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
14500 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
14510 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14520 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64  FIG_SCRATCH]] <d
14530 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14540 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
14550 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f  <dd> The SQLITE_
14560 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f  CONFIG_SCRATCH o
14570 70 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67  ption is no long
14580 65 72 20 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 64  er used..** </dd
14590 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
145a0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
145b0 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
145c0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
145d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
145e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
145f0 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e  PAGECACHE option
14600 20 73 70 65 63 69 66 69 65 73 20 61 20 6d 65 6d   specifies a mem
14610 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74  ory pool.** that
14620 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
14630 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
14640 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68   page cache with
14650 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67   the default pag
14660 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
14670 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  mentation.  .** 
14680 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
14690 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e  on option is a n
146a0 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c 69  o-op if an appli
146b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61  cation-define pa
146c0 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
146d0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f  ementation is lo
146e0 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  aded using the [
146f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14700 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72  ACHE2]..** ^Ther
14710 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
14720 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f  ments to SQLITE_
14730 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
14740 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  : A pointer to.*
14750 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  * 8-byte aligned
14760 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20   memory (pMem), 
14770 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
14780 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65   page cache line
14790 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
147a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63 68  e number of cach
147b0 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20  e lines (N)..** 
147c0 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
147d0 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69  should be the si
147e0 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ze of the larges
147f0 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a  t database page.
14800 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74  ** (a power of t
14810 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
14820 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73  nd 65536) plus s
14830 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20  ome extra bytes 
14840 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
14850 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e   header.  ^The n
14860 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62  umber of extra b
14870 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74  ytes needed by t
14880 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a  he page header.*
14890 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  * can be determi
148a0 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49 54  ned using [SQLIT
148b0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
148c0 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69  HDRSZ]..** ^It i
148d0 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72  s harmless, apar
148e0 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65  t from the waste
148f0 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72  d memory,.** for
14900 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65   the sz paramete
14910 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74  r to be larger t
14920 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20  han necessary.  
14930 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75  The pMem.** argu
14940 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69 74  ment must be eit
14950 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
14960 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20  er or a pointer 
14970 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  to an 8-byte.** 
14980 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66  aligned block of
14990 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65   memory of at le
149a0 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20  ast sz*N bytes, 
149b0 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75 62  otherwise.** sub
149c0 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
149d0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
149e0 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73 20  * ^When pMem is 
149f0 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65  not NULL, SQLite
14a00 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f 20   will strive to 
14a10 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  use the memory p
14a20 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61  rovided.** to sa
14a30 74 69 73 66 79 20 70 61 67 65 20 63 61 63 68 65  tisfy page cache
14a40 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20   needs, falling 
14a50 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33  back to [sqlite3
14a60 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a  _malloc()] if.**
14a70 20 61 20 70 61 67 65 20 63 61 63 68 65 20 6c 69   a page cache li
14a80 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74 68 61  ne is larger tha
14a90 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69 66  n sz bytes or if
14aa0 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d   all of the pMem
14ab0 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65 78   buffer.** is ex
14ac0 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20  hausted..** ^If 
14ad0 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64  pMem is NULL and
14ae0 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20   N is non-zero, 
14af0 74 68 65 6e 20 65 61 63 68 20 64 61 74 61 62 61  then each databa
14b00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
14b10 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61 6c   does an initial
14b20 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e   bulk allocation
14b30 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20   for page cache 
14b40 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b  memory.** from [
14b50 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14b60 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f 72  ] sufficient for
14b70 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20 69   N cache lines i
14b80 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 20  f N is positive 
14b90 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e  or.** of -1024*N
14ba0 20 62 79 74 65 73 20 69 66 20 4e 20 69 73 20 6e   bytes if N is n
14bb0 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20 61  egative, . ^If a
14bc0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67  dditional.** pag
14bd0 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69  e cache memory i
14be0 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20  s needed beyond 
14bf0 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
14c00 20 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c 0a   by the initial.
14c10 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  ** allocation, t
14c20 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73 20  hen SQLite goes 
14c30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
14c40 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c 79  oc()] separately
14c50 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64 64   for each.** add
14c60 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69  itional cache li
14c70 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ne. </dd>.**.** 
14c80 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14c90 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  HEAP]] <dt>SQLIT
14ca0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
14cb0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
14cc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
14cd0 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  AP option specif
14ce0 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
14cf0 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74  ory buffer .** t
14d00 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
14d10 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
14d20 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
14d30 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
14d40 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f  ds.** beyond tho
14d50 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  se provided for 
14d60 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
14d70 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
14d80 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
14d90 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20  FIG_HEAP option 
14da0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
14db0 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  e if SQLite is c
14dc0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
14dd0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45  either [SQLITE_E
14de0 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f  NABLE_MEMSYS3] o
14df0 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
14e00 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65  _MEMSYS5] and re
14e10 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
14e20 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b  _ERROR] if invok
14e30 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
14e40 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65   ^There are thre
14e50 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53  e arguments to S
14e60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
14e70 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20  P:.** An 8-byte 
14e80 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
14e90 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
14ea0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
14eb0 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
14ec0 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
14ed0 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
14ee0 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
14ef0 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
14f00 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
14f10 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
14f20 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
14f30 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
14f40 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
14f50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
14f60 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
14f70 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
14f80 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
14f90 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
14fa0 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
14fb0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
14fc0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
14fd0 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
14fe0 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68  not NULL then th
14ff0 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
15000 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
15010 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
15020 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
15030 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
15040 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
15050 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
15060 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
15070 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
15080 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
15090 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
150a0 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
150b0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
150c0 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
150d0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
150e0 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
150f0 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
15100 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61  t 2**12. Reasona
15110 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f  ble values.** fo
15120 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  r the minimum al
15130 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72  location size ar
15140 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32  e 2**5 through 2
15150 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  **8.</dd>.**.** 
15160 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15170 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
15180 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
15190 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
151a0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
151b0 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61  _MUTEX option ta
151c0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
151d0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
151e0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
151f0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
15200 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
15210 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
15220 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  ure..** The argu
15230 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61  ment specifies a
15240 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
15250 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
15260 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a  nes to be used.*
15270 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d  * in place the m
15280 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
15290 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
152a0 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
152b0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
152c0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
152d0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
152e0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
152f0 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
15300 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
15310 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
15320 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
15330 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
15340 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
15350 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
15360 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
15370 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
15380 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
15390 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
153a0 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
153b0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
153c0 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
153d0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
153e0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
153f0 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
15400 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
15410 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15420 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
15430 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
15440 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15450 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15460 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
15470 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
15480 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
15490 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
154a0 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69  IG_GETMUTEX opti
154b0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
154c0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
154d0 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
154e0 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
154f0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
15500 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
15510 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
15520 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
15530 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
15540 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
15550 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
15560 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
15570 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
15580 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
15590 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
155a0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
155b0 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
155c0 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
155d0 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
155e0 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
155f0 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
15600 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
15610 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
15620 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
15630 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
15640 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
15650 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
15660 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
15670 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
15680 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
15690 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
156a0 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
156b0 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
156c0 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
156d0 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
156e0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
156f0 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
15700 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15710 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
15720 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
15730 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
15740 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
15750 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15760 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
15770 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
15780 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
15790 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
157a0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
157b0 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f  _LOOKASIDE optio
157c0 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
157d0 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
157e0 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61  mine.** the defa
157f0 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b  ult size of look
15800 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20  aside memory on 
15810 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63  each [database c
15820 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  onnection]..** T
15830 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15840 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
15850 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
15860 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
15870 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
15880 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
15890 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
158a0 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
158b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
158c0 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49    ^(SQLITE_CONFI
158d0 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73  G_LOOKASIDE.** s
158e0 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75  ets the <i>defau
158f0 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65  lt</i> lookaside
15900 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49   size. The [SQLI
15910 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
15920 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e  ASIDE].** option
15930 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
15940 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
15950 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
15960 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
15970 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15980 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
15990 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
159a0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
159b0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
159c0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
159d0 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e  FIG_PCACHE2</dt>
159e0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
159f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
15a00 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
15a10 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
15a20 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a  ent which is .**
15a30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
15a40 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
15a50 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
15a60 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
15a70 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
15a80 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20   interface to a 
15a90 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
15aa0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
15ab0 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d  .)^.** ^SQLite m
15ac0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
15ad0 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  he [sqlite3_pcac
15ae0 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
15af0 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ect.</dd>.**.** 
15b00 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15b10 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  GETPCACHE2]] <dt
15b20 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
15b30 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  ETPCACHE2</dt>.*
15b40 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
15b50 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
15b60 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
15b70 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
15b80 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
15b90 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
15ba0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
15bb0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
15bc0 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
15bd0 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72  s of.** the curr
15be0 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ent page cache i
15bf0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
15c00 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
15c10 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
15c20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15c30 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  G]] <dt>SQLITE_C
15c40 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a  ONFIG_LOG</dt>.*
15c50 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54  * <dd> The SQLIT
15c60 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
15c70 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63  ion is used to c
15c80 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c  onfigure the SQL
15c90 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65  ite.** global [e
15ca0 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e  rror log]..** (^
15cb0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
15cc0 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
15cd0 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
15ce0 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
15cf0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
15d00 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
15d10 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
15d20 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
15d30 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
15d40 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
15d50 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
15d60 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
15d70 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
15d80 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
15d90 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
15da0 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
15db0 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
15dc0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
15dd0 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
15de0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
15df0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
15e00 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
15e10 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
15e20 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
15e30 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
15e40 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
15e50 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
15e60 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
15e70 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
15e80 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
15e90 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
15ea0 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
15eb0 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
15ec0 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
15ed0 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
15ee0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
15ef0 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
15f00 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
15f10 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
15f20 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
15f30 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
15f40 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
15f50 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
15f60 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
15f70 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
15f80 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
15f90 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
15fa0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
15fb0 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
15fc0 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
15fd0 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
15fe0 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
15ff0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
16000 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
16010 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
16020 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
16030 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
16040 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
16050 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
16060 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
16070 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
16080 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
16090 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
160a0 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
160b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
160c0 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
160d0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
160e0 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
160f0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
16100 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20  TE_CONFIG_URI]] 
16110 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16120 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54  G_URI.** <dd>^(T
16130 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
16140 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _URI option take
16150 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
16160 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e  ent of type int.
16170 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c  .** If non-zero,
16180 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
16190 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
161a0 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70  nabled. If the p
161b0 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f  arameter is zero
161c0 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61  ,.** then URI ha
161d0 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
161e0 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e  ly disabled.)^ ^
161f0 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  If URI handling 
16200 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65  is globally.** e
16210 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65  nabled, all file
16220 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20  names passed to 
16230 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
16240 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
16250 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
16260 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a  e3_open16()] or.
16270 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ** specified as 
16280 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d  part of [ATTACH]
16290 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e   commands are in
162a0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
162b0 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a  s, regardless.**
162c0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
162d0 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ot the [SQLITE_O
162e0 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
162f0 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61   set when the da
16300 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
16310 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
16320 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c  ^If it is global
16330 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c  ly disabled, fil
16340 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e  enames are.** on
16350 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ly interpreted a
16360 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51  s URIs if the SQ
16370 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c  LITE_OPEN_URI fl
16380 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
16390 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
163a0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
163b0 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c  ned. ^(By defaul
163c0 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  t, URI handling 
163d0 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64  is globally.** d
163e0 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66  isabled. The def
163f0 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62  ault value may b
16400 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d  e changed by com
16410 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a  piling with the.
16420 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  ** [SQLITE_USE_U
16430 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  RI] symbol defin
16440 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ed.)^.**.** [[SQ
16450 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
16460 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
16470 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
16480 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
16490 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e  EX_SCAN.** <dd>^
164a0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
164b0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
164c0 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b  _SCAN option tak
164d0 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65  es a single inte
164e0 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ger.** argument 
164f0 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72  which is interpr
16500 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
16510 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e  n in order to en
16520 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a  able or disable.
16530 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  ** the use of co
16540 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
16550 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
16560 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79  ans in the query
16570 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e   optimizer..** ^
16580 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
16590 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65  ing is determine
165a0 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c  d.** by the [SQL
165b0 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49  ITE_ALLOW_COVERI
165c0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63  NG_INDEX_SCAN] c
165d0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
165e0 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a  on, or is "on".*
165f0 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c  * if that compil
16600 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
16610 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65   omitted..** The
16620 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61   ability to disa
16630 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63  ble the use of c
16640 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
16650 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
16660 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75  cans.** is becau
16670 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63  se some incorrec
16680 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79  tly coded legacy
16690 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69   applications mi
166a0 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a  ght malfunction.
166b0 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69  ** when the opti
166c0 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  mization is enab
166d0 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20  led.  Providing 
166e0 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a  the ability to.*
166f0 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70  * disable the op
16700 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77  timization allow
16710 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67  s the older, bug
16720 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  gy application c
16730 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ode to work.** w
16740 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76  ithout change ev
16750 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65  en with newer ve
16760 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
16770 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
16780 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d  _CONFIG_PCACHE]]
16790 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
167a0 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20  _GETPCACHE]].** 
167b0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
167c0 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c  G_PCACHE and SQL
167d0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
167e0 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  ACHE.** <dd> The
167f0 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f  se options are o
16800 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75  bsolete and shou
16810 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62  ld not be used b
16820 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54  y new code..** T
16830 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64  hey are retained
16840 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
16850 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74  ompatibility but
16860 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e   are now no-ops.
16870 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
16880 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16890 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e  SQLLOG]].** <dt>
168a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
168b0 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  LLOG.** <dd>This
168c0 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
168d0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c  available if sql
168e0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
168f0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
16900 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f  ITE_ENABLE_SQLLO
16910 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  G] pre-processor
16920 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20   macro defined. 
16930 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
16940 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20  nt should.** be 
16950 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66  a pointer to a f
16960 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
16970 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
16980 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61  lite3*,const cha
16990 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65  r*, int)..** The
169a0 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62   second should b
169b0 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a  e of type (void*
169c0 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ). The callback 
169d0 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68  is invoked by th
169e0 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20  e library.** in 
169f0 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63  three separate c
16a00 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64  ircumstances, id
16a10 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
16a20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
16a30 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
16a40 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20  rameter. If the 
16a50 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
16a60 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20   is 0, then the 
16a70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16a80 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73  ion.** passed as
16a90 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
16aa0 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65  ment has just be
16ab0 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74  en opened. The t
16ac0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
16ad0 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66   points to a buf
16ae0 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  fer containing t
16af0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
16b00 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
16b10 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75  e. If the.** fou
16b20 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
16b30 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c   1, then the SQL
16b40 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
16b50 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
16b60 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ter.** points to
16b70 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65   has just been e
16b80 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20  xecuted. Or, if 
16b90 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
16ba0 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a  eter is 2, then.
16bb0 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ** the connectio
16bc0 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61  n being passed a
16bd0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
16be0 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20  ameter is being 
16bf0 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74  closed. The.** t
16c00 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
16c10 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e  s passed NULL In
16c20 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20   this case.  An 
16c30 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67  example of using
16c40 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75   this.** configu
16c50 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61  ration option ca
16c60 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65  n be seen in the
16c70 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22   "test_sqllog.c"
16c80 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a   source file in.
16c90 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c  ** the canonical
16ca0 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74   SQLite source t
16cb0 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ree.</dd>.**.** 
16cc0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16cd0 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  MMAP_SIZE]].** <
16ce0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16cf0 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64  _MMAP_SIZE.** <d
16d00 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d>^SQLITE_CONFIG
16d10 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73  _MMAP_SIZE takes
16d20 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65   two 64-bit inte
16d30 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74  ger (sqlite3_int
16d40 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  64) values.** th
16d50 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75  at are the defau
16d60 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  lt mmap size lim
16d70 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20  it (the default 
16d80 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b  setting for.** [
16d90 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
16da0 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ]) and the maxim
16db0 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
16dc0 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e  size limit..** ^
16dd0 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
16de0 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72  ing can be overr
16df0 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61  idden by each da
16e00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16e10 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65  n using.** eithe
16e20 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d  r the [PRAGMA mm
16e30 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64  ap_size] command
16e40 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68  , or by using th
16e50 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
16e60 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
16e70 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54  le control.  ^(T
16e80 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
16e90 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20  ed mmap size.** 
16ea0 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79  will be silently
16eb0 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65   truncated if ne
16ec0 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20  cessary so that 
16ed0 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65  it does not exce
16ee0 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  ed the.** compil
16ef0 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
16f00 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
16f10 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
16f20 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
16f30 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
16f40 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68  n.)^.** ^If eith
16f50 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  er argument to t
16f60 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65  his option is ne
16f70 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61  gative, then tha
16f80 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  t argument is.**
16f90 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20   changed to its 
16fa0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66  compile-time def
16fb0 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ault..**.** [[SQ
16fc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
16fd0 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20  2_HEAPSIZE]].** 
16fe0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16ff0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
17000 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
17010 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
17020 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e  _HEAPSIZE option
17030 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
17040 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a  le if SQLite is.
17050 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  ** compiled for 
17060 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65  Windows with the
17070 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d   [SQLITE_WIN32_M
17080 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65  ALLOC] pre-proce
17090 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65  ssor macro.** de
170a0 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43  fined. ^SQLITE_C
170b0 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
170c0 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d  SIZE takes a 32-
170d0 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
170e0 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68  eger value.** th
170f0 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  at specifies the
17100 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
17110 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61   the created hea
17120 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  p..**.** [[SQLIT
17130 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
17140 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  HDRSZ]].** <dt>S
17150 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
17160 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64  CHE_HDRSZ.** <dd
17170 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
17180 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
17190 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
171a0 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
171b0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
171c0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
171d0 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20  eger and writes 
171e0 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
171f0 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  r the number of 
17200 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70  extra.** bytes p
17210 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64  er page required
17220 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69   for each page i
17230 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  n [SQLITE_CONFIG
17240 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
17250 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78  The amount of ex
17260 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72  tra space requir
17270 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65  ed can change de
17280 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
17290 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67  ompiler,.** targ
172a0 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64  et platform, and
172b0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e   SQLite version.
172c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
172d0 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a  CONFIG_PMASZ]].*
172e0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
172f0 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64  FIG_PMASZ.** <dd
17300 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
17310 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e  FIG_PMASZ option
17320 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
17330 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
17340 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65  ** is an unsigne
17350 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65  d integer and se
17360 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20  ts the "Minimum 
17370 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68  PMA Size" for th
17380 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a  e multithreaded.
17390 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61  ** sorter to tha
173a0 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20  t integer.  The 
173b0 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20  default minimum 
173c0 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20  PMA Size is set 
173d0 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
173e0 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20  E_SORTER_PMASZ] 
173f0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
17400 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64  ion.  New thread
17410 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a  s are launched.*
17420 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73  * to help with s
17430 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77  ort operations w
17440 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65  hen multithreade
17450 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20  d sorting.** is 
17460 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74  enabled (using t
17470 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61  he [PRAGMA threa
17480 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64  ds] command) and
17490 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63   the amount of c
174a0 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20  ontent.** to be 
174b0 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74  sorted exceeds t
174c0 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d  he page size tim
174d0 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f  es the minimum o
174e0 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41  f the.** [PRAGMA
174f0 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74   cache_size] set
17500 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61  ting and this va
17510 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  lue..**.** [[SQL
17520 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
17530 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c  RNL_SPILL]].** <
17540 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17550 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a  _STMTJRNL_SPILL.
17560 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
17570 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
17580 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e 20  NL_SPILL option 
17590 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
175a0 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
175b0 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b 73  * becomes the [s
175c0 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c  tatement journal
175d0 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20  ] spill-to-disk 
175e0 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20  threshold.  .** 
175f0 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e  [Statement journ
17600 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69 6e  als] are held in
17610 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74 68   memory until th
17620 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79 74  eir size (in byt
17630 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20 74  es).** exceeds t
17640 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20 61  his threshold, a
17650 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74 68  t which point th
17660 65 79 20 61 72 65 20 77 72 69 74 74 65 6e 20 74  ey are written t
17670 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66  o disk..** Or if
17680 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20 69   the threshold i
17690 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74 20  s -1, statement 
176a0 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c 77  journals are alw
176b0 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63 6c  ays held.** excl
176c0 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f 72  usively in memor
176d0 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e 79  y..** Since many
176e0 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e   statement journ
176f0 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d 65  als never become
17700 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67 20   large, setting 
17710 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68 72  the spill.** thr
17720 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c 75  eshold to a valu
17730 65 20 73 75 63 68 20 61 73 20 36 34 4b 69 42 20  e such as 64KiB 
17740 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64 75  can greatly redu
17750 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  ce the amount of
17760 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65 64  .** I/O required
17770 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61 74   to support stat
17780 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a  ement rollback..
17790 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  ** The default v
177a0 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73 65  alue for this se
177b0 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f 6c  tting is control
177c0 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53  led by the.** [S
177d0 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53  QLITE_STMTJRNL_S
177e0 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  PILL] compile-ti
177f0 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f  me option..** </
17800 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
17810 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
17820 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
17830 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
17840 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
17850 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
17860 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
17870 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
17880 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
17890 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
178a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
178b0 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
178c0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
178d0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
178e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
178f0 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20  G_GETMALLOC     
17900 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  5  /* sqlite3_me
17910 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
17920 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17930 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20  FIG_SCRATCH     
17940 20 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65    6  /* No longe
17950 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e  r used */.#defin
17960 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17970 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
17980 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
17990 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
179a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
179b0 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
179c0 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
179d0 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
179e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
179f0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
17a00 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
17a10 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
17a20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
17a30 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
17a40 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
17a50 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
17a60 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17a70 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
17a80 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
17a90 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
17aa0 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
17ab0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
17ac0 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
17ad0 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
17ae0 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
17af0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
17b00 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
17b10 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
17b20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
17b30 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
17b40 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
17b50 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17b60 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
17b70 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
17b80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17b90 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
17ba0 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
17bb0 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
17bc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
17bd0 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
17be0 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
17bf0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
17c00 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
17c10 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
17c20 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
17c30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17c40 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
17c50 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
17c60 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
17c70 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
17c80 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
17c90 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
17ca0 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
17cb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17cc0 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
17cd0 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
17ce0 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
17cf0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
17d00 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20  MAP_SIZE    22  
17d10 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
17d20 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
17d30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17d40 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
17d50 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20  EAPSIZE      23 
17d60 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
17d70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17d80 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
17d90 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f  RSZ        24  /
17da0 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64  * int *psz */.#d
17db0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17dc0 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20  FIG_PMASZ       
17dd0 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75          25  /* u
17de0 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d  nsigned int szPm
17df0 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  a */.#define SQL
17e00 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
17e10 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32  RNL_SPILL      2
17e20 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20  6  /* int nByte 
17e30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17e40 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d  E_CONFIG_SMALL_M
17e50 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 32 37 20  ALLOC        27 
17e60 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 0a   /* boolean */..
17e70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17e80 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
17e90 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
17ea0 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
17eb0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
17ec0 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
17ed0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
17ee0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
17ef0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
17f00 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
17f10 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
17f20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
17f30 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
17f40 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
17f50 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
17f60 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
17f70 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
17f80 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
17f90 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
17fa0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
17fb0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
17fc0 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
17fd0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
17fe0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
17ff0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
18000 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
18010 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
18020 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
18030 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
18040 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
18050 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
18060 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
18070 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
18080 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
18090 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
180a0 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
180b0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
180c0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
180d0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
180e0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
180f0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
18100 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
18110 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
18120 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
18130 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
18140 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
18150 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
18160 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
18170 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
18180 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
18190 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
181a0 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
181b0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
181c0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
181d0 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
181e0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
181f0 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
18200 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
18210 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
18220 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
18230 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
18240 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
18250 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
18260 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
18270 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
18280 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
18290 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
182a0 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
182b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
182c0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
182d0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
182e0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
182f0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
18300 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
18310 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
18320 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
18330 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
18340 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
18350 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
18360 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
18370 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
18380 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
18390 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
183a0 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
183b0 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
183c0 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
183d0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
183e0 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
183f0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
18400 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
18410 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
18420 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
18430 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
18440 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
18450 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
18460 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
18470 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  r multiple of 8.
18480 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64    ^(The lookasid
18490 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66  e memory.** conf
184a0 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20  iguration for a 
184b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
184c0 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ion can only be 
184d0 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61  changed when tha
184e0 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  t.** connection 
184f0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
18500 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65   using lookaside
18510 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f   memory, or in o
18520 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68  ther words.** wh
18530 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20  en the "current 
18540 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20  value" returned 
18550 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64  by.** [sqlite3_d
18560 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c  b_status](D,[SQL
18570 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
18580 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65  SIDE],...) is ze
18590 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ro..** Any attem
185a0 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  pt to change the
185b0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
185c0 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  y configuration 
185d0 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a  when lookaside.*
185e0 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75  * memory is in u
185f0 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f  se leaves the co
18600 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68  nfiguration unch
18610 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
18620 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  s .** [SQLITE_BU
18630 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  SY].)^</dd>.**.*
18640 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
18650 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
18660 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  Y</dt>.** <dd> ^
18670 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
18680 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
18690 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66   disable the enf
186a0 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b  orcement of.** [
186b0 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
186c0 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65  traints].  There
186d0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
186e0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
186f0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
18700 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
18710 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
18720 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46  s 0 to disable F
18730 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a  K enforcement,.*
18740 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
18750 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
18760 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ent or negative 
18770 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f  to leave FK enfo
18780 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61  rcement.** uncha
18790 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e  nged.  The secon
187a0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
187b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
187c0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
187d0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
187e0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
187f0 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e  te whether FK en
18800 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66  forcement is off
18810 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77   or on.** follow
18820 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
18830 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
18840 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
18850 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
18860 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
18870 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
18880 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
18890 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
188a0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
188b0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
188c0 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74  ABLE_TRIGGER</dt
188d0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
188e0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
188f0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
18900 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47  ble [CREATE TRIG
18910 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e  GER | triggers].
18920 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
18930 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
18940 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
18950 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
18960 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
18970 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
18980 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73  disable triggers
18990 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
189a0 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73   enable triggers
189b0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
189c0 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
189d0 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
189e0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
189f0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
18a00 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
18a10 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
18a20 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
18a30 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
18a40 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65  her triggers are
18a50 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
18a60 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
18a70 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
18a80 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18a90 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
18aa0 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
18ab0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74  which case the t
18ac0 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69  rigger setting i
18ad0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
18ae0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
18af0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
18b00 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33  NFIG_ENABLE_FTS3
18b10 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a  _TOKENIZER</dt>.
18b20 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
18b30 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
18b40 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
18b50 65 20 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65  e the two-argume
18b60 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  nt.** version of
18b70 20 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e   the [fts3_token
18b80 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e  izer()] function
18b90 20 77 68 69 63 68 20 69 73 20 70 61 72 74 20 6f   which is part o
18ba0 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20  f the.** [FTS3] 
18bb0 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68  full-text search
18bc0 20 65 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f   engine extensio
18bd0 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  n..** There shou
18be0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
18bf0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
18c00 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
18c10 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
18c20 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
18c30 6f 20 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74  o disable fts3_t
18c40 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a  okenizer() or.**
18c50 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
18c60 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  ble fts3_tokeniz
18c70 65 72 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65  er() or negative
18c80 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
18c90 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67  tting.** unchang
18ca0 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
18cb0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
18cc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
18cd0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
18ce0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
18cf0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
18d00 74 65 20 77 68 65 74 68 65 72 20 66 74 73 33 5f  te whether fts3_
18d10 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73  tokenizer is dis
18d20 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
18d30 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
18d40 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
18d50 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
18d60 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
18d70 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
18d80 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73  h case the new s
18d90 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
18da0 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
18db0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18dc0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
18dd0 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49  BLE_LOAD_EXTENSI
18de0 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ON</dt>.** <dd> 
18df0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
18e00 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
18e10 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73  r disable the [s
18e20 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
18e30 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65  nsion()].** inte
18e40 72 66 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e  rface independen
18e50 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64  tly of the [load
18e60 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51  _extension()] SQ
18e70 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  L function..** T
18e80 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  he [sqlite3_enab
18e90 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
18ea0 6e 28 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73  n()] API enables
18eb0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74   or disables bot
18ec0 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b  h the.** C-API [
18ed0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
18ee0 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68  ension()] and th
18ef0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b  e SQL function [
18f00 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
18f10 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
18f20 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
18f30 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
18f40 2a 2a 20 57 68 65 6e 20 74 68 65 20 66 69 72 73  ** When the firs
18f50 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
18f60 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
18f70 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65  1, then only the
18f80 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61   C-API is.** ena
18f90 62 6c 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  bled and the SQL
18fa0 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e   function remain
18fb0 73 20 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20  s disabled.  If 
18fc0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
18fd0 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e  nt to.** this in
18fe0 74 65 72 66 61 63 65 20 69 73 20 30 2c 20 74 68  terface is 0, th
18ff0 65 6e 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50  en both the C-AP
19000 49 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75  I and the SQL fu
19010 6e 63 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62  nction are disab
19020 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  led..** If the f
19030 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
19040 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61   -1, then no cha
19050 6e 67 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f  nges are made to
19060 20 73 74 61 74 65 20 6f 66 20 65 69 74 68 65 72   state of either
19070 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72   the.** C-API or
19080 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
19090 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  n..** The second
190a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
190b0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
190c0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
190d0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
190e0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
190f0 65 20 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74  e whether [sqlit
19100 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
19110 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  n()] interface.*
19120 2a 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72  * is disabled or
19130 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69   enabled followi
19140 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
19150 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
19160 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20  ter may.** be a 
19170 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
19180 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
19190 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e  new setting is n
191a0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
191b0 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
191c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
191d0 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c  NFIG_MAINDBNAME<
191e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
191f0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
19200 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
19210 6e 61 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69  name of the "mai
19220 6e 22 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73  n" database.** s
19230 63 68 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c  chema.  ^The sol
19240 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
19250 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e  pointer to a con
19260 73 74 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e  stant UTF8 strin
19270 67 0a 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20  g.** which will 
19280 62 65 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73  become the new s
19290 63 68 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c  chema name in pl
192a0 61 63 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20  ace of "main".  
192b0 5e 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20  ^SQLite.** does 
192c0 6e 6f 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  not make a copy 
192d0 6f 66 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20  of the new main 
192e0 73 63 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69  schema name stri
192f0 6e 67 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69  ng, so the appli
19300 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65  cation.** must e
19310 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61  nsure that the a
19320 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
19330 6e 74 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49  nto this DBCONFI
19340 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68  G option is unch
19350 61 6e 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61  anged.** until a
19360 66 74 65 72 20 74 68 65 20 64 61 74 61 62 61 73  fter the databas
19370 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
19380 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ses..** </dd>.**
19390 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
193a0 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f  BCONFIG_NO_CKPT_
193b0 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a  ON_CLOSE</dt>.**
193c0 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77   <dd> Usually, w
193d0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 69  hen a database i
193e0 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c  n wal mode is cl
193f0 6f 73 65 64 20 6f 72 20 64 65 74 61 63 68 65 64  osed or detached
19400 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61   from a .** data
19410 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c  base handle, SQL
19420 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 68  ite checks if th
19430 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61  is will mean tha
19440 74 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20  t there are now 
19450 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  no .** connectio
19460 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65  ns at all to the
19470 20 64 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f   database. If so
19480 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20  , it performs a 
19490 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f  checkpoint .** o
194a0 70 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20  peration before 
194b0 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e  closing the conn
194c0 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74  ection. This opt
194d0 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20  ion may be used 
194e0 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74  to.** override t
194f0 68 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54  his behaviour. T
19500 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
19510 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69  er passed to thi
19520 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69  s operation.** i
19530 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 6e  s an integer - n
19540 6f 6e 2d 7a 65 72 6f 20 74 6f 20 64 69 73 61 62  on-zero to disab
19550 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f  le checkpoints-o
19560 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f  n-close, or zero
19570 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74   (the.** default
19580 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d  ) to enable them
19590 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  . The second par
195a0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
195b0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
195c0 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20  r.** into which 
195d0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
195e0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
195f0 65 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74  ether checkpoint
19600 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61  s-on-close.** ha
19610 76 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64  ve been disabled
19620 20 2d 20 30 20 69 66 20 74 68 65 79 20 61 72 65   - 0 if they are
19630 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31   not disabled, 1
19640 20 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a   if they are..**
19650 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 64 74 3e 53 51   </dd>.** <dt>SQ
19660 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
19670 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74 3e 0a 2a  ABLE_QPSG</dt>.*
19680 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49  * <dd>^(The SQLI
19690 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
196a0 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f 6e 20 61  LE_QPSG option a
196b0 63 74 69 76 61 74 65 73 20 6f 72 20 64 65 61 63  ctivates or deac
196c0 74 69 76 61 74 65 73 0a 2a 2a 20 74 68 65 20 5b  tivates.** the [
196d0 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 73 74  query planner st
196e0 61 62 69 6c 69 74 79 20 67 75 61 72 61 6e 74 65  ability guarante
196f0 65 5d 20 28 51 50 53 47 29 2e 20 20 57 68 65 6e  e] (QPSG).  When
19700 20 74 68 65 20 51 50 53 47 20 69 73 20 61 63 74   the QPSG is act
19710 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e 67 6c 65  ive,.** a single
19720 20 53 51 4c 20 71 75 65 72 79 20 73 74 61 74 65   SQL query state
19730 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77 61 79 73  ment will always
19740 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 61 6c   use the same al
19750 67 6f 72 69 74 68 6d 20 72 65 67 61 72 64 6c 65  gorithm regardle
19760 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75 65 73 20  ss.** of values 
19770 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  of [bound parame
19780 74 65 72 73 5d 2e 29 5e 20 54 68 65 20 51 50 53  ters].)^ The QPS
19790 47 20 64 69 73 61 62 6c 65 73 20 73 6f 6d 65 20  G disables some 
197a0 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 61 74 69  query optimizati
197b0 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c 6f 6f 6b  ons.** that look
197c0 20 61 74 20 74 68 65 20 76 61 6c 75 65 73 20 6f   at the values o
197d0 66 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  f bound paramete
197e0 72 73 2c 20 77 68 69 63 68 20 63 61 6e 20 6d 61  rs, which can ma
197f0 6b 65 20 73 6f 6d 65 20 71 75 65 72 69 65 73 0a  ke some queries.
19800 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42 75 74 20  ** slower.  But 
19810 74 68 65 20 51 50 53 47 20 68 61 73 20 74 68 65  the QPSG has the
19820 20 61 64 76 61 6e 74 61 67 65 20 6f 66 20 6d 6f   advantage of mo
19830 72 65 20 70 72 65 64 69 63 74 61 62 6c 65 20 62  re predictable b
19840 65 68 61 76 69 6f 72 2e 20 20 57 69 74 68 0a 2a  ehavior.  With.*
19850 2a 20 74 68 65 20 51 50 53 47 20 61 63 74 69 76  * the QPSG activ
19860 65 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  e, SQLite will a
19870 6c 77 61 79 73 20 75 73 65 20 74 68 65 20 73 61  lways use the sa
19880 6d 65 20 71 75 65 72 79 20 70 6c 61 6e 20 69 6e  me query plan in
19890 20 74 68 65 20 66 69 65 6c 64 20 61 73 0a 2a 2a   the field as.**
198a0 20 77 61 73 20 75 73 65 64 20 64 75 72 69 6e 67   was used during
198b0 20 74 65 73 74 69 6e 67 20 69 6e 20 74 68 65 20   testing in the 
198c0 6c 61 62 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  lab..** </dd>.**
198d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
198e0 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50  NFIG_TRIGGER_EQP
198f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 42 79  </dt>.** <dd> By
19900 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 6f 75   default, the ou
19910 74 70 75 74 20 6f 66 20 45 58 50 4c 41 49 4e 20  tput of EXPLAIN 
19920 51 55 45 52 59 20 50 4c 41 4e 20 63 6f 6d 6d 61  QUERY PLAN comma
19930 6e 64 73 20 64 6f 65 73 20 6e 6f 74 20 0a 2a 2a  nds does not .**
19940 20 69 6e 63 6c 75 64 65 20 6f 75 74 70 75 74 20   include output 
19950 66 6f 72 20 61 6e 79 20 6f 70 65 72 61 74 69 6f  for any operatio
19960 6e 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ns performed by 
19970 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
19980 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74 69 6f 6e  . This.** option
19990 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
199a0 6f 72 20 63 6c 65 61 72 20 28 74 68 65 20 64 65  or clear (the de
199b0 66 61 75 6c 74 29 20 61 20 66 6c 61 67 20 74 68  fault) a flag th
199c0 61 74 20 67 6f 76 65 72 6e 73 20 74 68 69 73 0a  at governs this.
199d0 2a 2a 20 62 65 68 61 76 69 6f 72 2e 20 54 68 65  ** behavior. The
199e0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
199f0 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20   passed to this 
19a00 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
19a10 69 6e 74 65 67 65 72 20 2d 0a 2a 2a 20 6e 6f 6e  integer -.** non
19a20 2d 7a 65 72 6f 20 74 6f 20 65 6e 61 62 6c 65 20  -zero to enable 
19a30 6f 75 74 70 75 74 20 66 6f 72 20 74 72 69 67 67  output for trigg
19a40 65 72 20 70 72 6f 67 72 61 6d 73 2c 20 6f 72 20  er programs, or 
19a50 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20  zero to disable 
19a60 69 74 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  it..** The secon
19a70 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
19a80 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
19a90 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
19aa0 68 20 69 73 20 77 72 69 74 74 65 6e 20 0a 2a 2a  h is written .**
19ab0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
19ac0 61 74 65 20 77 68 65 74 68 65 72 20 6f 75 74 70  ate whether outp
19ad0 75 74 2d 66 6f 72 2d 74 72 69 67 67 65 72 73 20  ut-for-triggers 
19ae0 68 61 73 20 62 65 65 6e 20 64 69 73 61 62 6c 65  has been disable
19af0 64 20 2d 20 30 20 69 66 20 0a 2a 2a 20 69 74 20  d - 0 if .** it 
19b00 69 73 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c  is not disabled,
19b10 20 31 20 69 66 20 69 74 20 69 73 2e 20 20 0a 2a   1 if it is.  .*
19b20 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e  * </dd>.** </dl>
19b30 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
19b40 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e  TE_DBCONFIG_MAIN
19b50 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  DBNAME          
19b60 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20    1000 /* const 
19b70 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  char* */.#define
19b80 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
19b90 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20  _LOOKASIDE      
19ba0 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76         1001 /* v
19bb0 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
19bc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19bd0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
19be0 4b 45 59 20 20 20 20 20 20 20 20 20 20 20 31 30  KEY           10
19bf0 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  02 /* int int* *
19c00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19c10 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
19c20 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
19c30 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1003 /* int int*
19c40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19c50 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
19c60 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45  LE_FTS3_TOKENIZE
19c70 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e  R 1004 /* int in
19c80 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
19c90 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
19ca0 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53  ABLE_LOAD_EXTENS
19cb0 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20  ION 1005 /* int 
19cc0 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
19cd0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19ce0 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45  NO_CKPT_ON_CLOSE
19cf0 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e        1006 /* in
19d00 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
19d10 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
19d20 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 20 20  G_ENABLE_QPSG   
19d30 20 20 20 20 20 20 20 20 31 30 30 37 20 2f 2a 20          1007 /* 
19d40 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
19d50 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
19d60 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50 20  FIG_TRIGGER_EQP 
19d70 20 20 20 20 20 20 20 20 20 20 31 30 30 38 20 2f            1008 /
19d80 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
19d90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
19da0 4f 4e 46 49 47 5f 4d 41 58 20 20 20 20 20 20 20  ONFIG_MAX       
19db0 20 20 20 20 20 20 20 20 20 20 20 20 31 30 30 38              1008
19dc0 20 2f 2a 20 4c 61 72 67 65 73 74 20 44 42 43 4f   /* Largest DBCO
19dd0 4e 46 49 47 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  NFIG */../*.** C
19de0 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
19df0 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
19e00 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
19e10 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
19e20 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
19e30 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
19e40 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
19e50 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
19e60 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
19e70 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
19e80 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
19e90 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68  e of SQLite. ^Th
19ea0 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
19eb0 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64  t.** codes are d
19ec0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
19ed0 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  lt for historica
19ee0 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  l compatibility.
19ef0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
19f00 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
19f10 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
19f20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
19f30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
19f40 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a  t Insert Rowid.*
19f50 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
19f60 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e  3.**.** ^Each en
19f70 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69  try in most SQLi
19f80 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 70  te tables (excep
19f90 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52  t for [WITHOUT R
19fa0 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a  OWID] tables).**
19fb0 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34   has a unique 64
19fc0 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69  -bit signed.** i
19fd0 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65  nteger key calle
19fe0 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22  d the [ROWID | "
19ff0 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f  rowid"]. ^The ro
1a000 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
1a010 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
1a020 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
1a030 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
1a040 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
1a050 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
1a060 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
1a070 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
1a080 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
1a090 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a  ed columns. ^If.
1a0a0 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
1a0b0 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
1a0c0 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  e [INTEGER PRIMA
1a0d0 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61  RY KEY] then tha
1a0e0 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61  t column.** is a
1a0f0 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72  nother alias for
1a100 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a   the rowid..**.*
1a110 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  * ^The sqlite3_l
1a120 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1a130 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 75 73  (D) interface us
1a140 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
1a150 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a 2a 20  e [rowid] of.** 
1a160 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
1a170 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
1a180 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64  RT] into a rowid
1a190 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75   table or [virtu
1a1a0 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20  al table].** on 
1a1b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a1c0 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72 74 73 20  ion D. ^Inserts 
1a1d0 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f  into [WITHOUT RO
1a1e0 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20  WID] tables are 
1a1f0 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64 65 64 2e  not.** recorded.
1a200 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66   ^If no successf
1a210 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74  ul [INSERT]s int
1a220 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 68  o rowid tables h
1a230 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
1a240 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20 64 61 74  d .** on the dat
1a250 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a260 20 44 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33   D, then sqlite3
1a270 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1a280 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 0a 2a  id(D) returns .*
1a290 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 41 73  * zero..**.** As
1a2a0 20 77 65 6c 6c 20 61 73 20 62 65 69 6e 67 20 73   well as being s
1a2b0 65 74 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  et automatically
1a2c0 20 61 73 20 72 6f 77 73 20 61 72 65 20 69 6e 73   as rows are ins
1a2d0 65 72 74 65 64 20 69 6e 74 6f 20 64 61 74 61 62  erted into datab
1a2e0 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73 2c 20 74  ase.** tables, t
1a2f0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1a300 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69  d by this functi
1a310 6f 6e 20 6d 61 79 20 62 65 20 73 65 74 20 65 78  on may be set ex
1a320 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a 2a 20 5b  plicitly by.** [
1a330 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74  sqlite3_set_last
1a340 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
1a350 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69 72 74  .**.** Some virt
1a360 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
1a370 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 49 4e  entations may IN
1a380 53 45 52 54 20 72 6f 77 73 20 69 6e 74 6f 20 72  SERT rows into r
1a390 6f 77 69 64 20 74 61 62 6c 65 73 20 61 73 0a 2a  owid tables as.*
1a3a0 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d 6d 69 74  * part of commit
1a3b0 74 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69  ting a transacti
1a3c0 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66 6c 75 73  on (e.g. to flus
1a3d0 68 20 64 61 74 61 20 61 63 63 75 6d 75 6c 61 74  h data accumulat
1a3e0 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ed in memory.** 
1a3f0 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20 74 68 69  to disk). In thi
1a400 73 20 63 61 73 65 20 73 75 62 73 65 71 75 65 6e  s case subsequen
1a410 74 20 63 61 6c 6c 73 20 74 6f 20 74 68 69 73 20  t calls to this 
1a420 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 20  function return 
1a430 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 61 73 73  the rowid.** ass
1a440 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
1a450 73 65 20 69 6e 74 65 72 6e 61 6c 20 49 4e 53 45  se internal INSE
1a460 52 54 20 6f 70 65 72 61 74 69 6f 6e 73 2c 20 77  RT operations, w
1a470 68 69 63 68 20 6c 65 61 64 73 20 74 6f 20 0a 2a  hich leads to .*
1a480 2a 20 75 6e 69 6e 74 75 69 74 69 76 65 20 72 65  * unintuitive re
1a490 73 75 6c 74 73 2e 20 56 69 72 74 75 61 6c 20 74  sults. Virtual t
1a4a0 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
1a4b0 69 6f 6e 73 20 74 68 61 74 20 64 6f 20 77 72 69  ions that do wri
1a4c0 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a 2a 20 74  te to rowid.** t
1a4d0 61 62 6c 65 73 20 69 6e 20 74 68 69 73 20 77 61  ables in this wa
1a4e0 79 20 63 61 6e 20 61 76 6f 69 64 20 74 68 69 73  y can avoid this
1a4f0 20 70 72 6f 62 6c 65 6d 20 62 79 20 72 65 73 74   problem by rest
1a500 6f 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e  oring the origin
1a510 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20 76 61 6c  al .** rowid val
1a520 75 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ue using [sqlite
1a530 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72  3_set_last_inser
1a540 74 5f 72 6f 77 69 64 28 29 5d 20 62 65 66 6f 72  t_rowid()] befor
1a550 65 20 72 65 74 75 72 6e 69 6e 67 20 0a 2a 2a 20  e returning .** 
1a560 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68 65 20 75  control to the u
1a570 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ser..**.** ^(If 
1a580 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75  an [INSERT] occu
1a590 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  rs within a trig
1a5a0 67 65 72 20 74 68 65 6e 20 74 68 69 73 20 72 6f  ger then this ro
1a5b0 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a 20 72  utine will .** r
1a5c0 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64  eturn the [rowid
1a5d0 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65  ] of the inserte
1a5e0 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73  d row as long as
1a5f0 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73 20   the trigger is 
1a600 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f 6e 63  .** running. Onc
1a610 65 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72  e the trigger pr
1a620 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74 68 65 20  ogram ends, the 
1a630 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a  value returned .
1a640 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ** by this routi
1a650 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68  ne reverts to wh
1a660 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65  at it was before
1a670 20 74 68 65 20 74 72 69 67 67 65 72 20 77 61 73   the trigger was
1a680 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20   fired.)^.**.** 
1a690 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61  ^An [INSERT] tha
1a6a0 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
1a6b0 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
1a6c0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
1a6d0 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
1a6e0 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e  SERT] and does n
1a6f0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
1a700 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1a710 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e  this.** routine.
1a720 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f    ^Thus INSERT O
1a730 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
1a740 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
1a750 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
1a760 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
1a770 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
1a780 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
1a790 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
1a7a0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
1a7b0 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
1a7c0 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20   fails.  ^(When 
1a7d0 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
1a7e0 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
1a7f0 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
1a800 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
1a810 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
1a820 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
1a830 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
1a840 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
1a850 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
1a860 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
1a870 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
1a880 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
1a890 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
1a8a0 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
1a8b0 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
1a8c0 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a  nterface.)^.**.*
1a8d0 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
1a8e0 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
1a8f0 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ine, an [INSERT]
1a900 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
1a910 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
1a920 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
1a930 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
1a940 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
1a950 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
1a960 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20  s accessible to 
1a970 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76  SQL statements v
1a980 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f  ia the.** [last_
1a990 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53  insert_rowid() S
1a9a0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
1a9b0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
1a9c0 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
1a9d0 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d  s a new [INSERT]
1a9e0 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
1a9f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1aa00 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
1aa10 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
1aa20 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66  rt_rowid()].** f
1aa30 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
1aa40 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
1aa50 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
1aa60 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20  ert [rowid],.** 
1aa70 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
1aa80 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1aa90 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1aaa0 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75  rowid()] is.** u
1aab0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
1aac0 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
1aad0 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
1aae0 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61  or the new.** la
1aaf0 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
1ab00 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  ]..*/.sqlite3_in
1ab10 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  t64 sqlite3_last
1ab20 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
1ab30 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1ab40 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 74 68  CAPI3REF: Set th
1ab50 65 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  e Last Insert Ro
1ab60 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d 45  wid value..** ME
1ab70 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1ab80 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1ab90 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  set_last_insert_
1aba0 72 6f 77 69 64 28 44 2c 20 52 29 20 6d 65 74 68  rowid(D, R) meth
1abb0 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65 20 61 70  od allows the ap
1abc0 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20  plication to.** 
1abd0 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 72 65  set the value re
1abe0 74 75 72 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  turned by callin
1abf0 67 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  g sqlite3_last_i
1ac00 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 74  nsert_rowid(D) t
1ac10 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75 74 20  o R .** without 
1ac20 69 6e 73 65 72 74 69 6e 67 20 61 20 72 6f 77 20  inserting a row 
1ac30 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
1ac40 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  e..*/.void sqlit
1ac50 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65  e3_set_last_inse
1ac60 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
1ac70 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
1ac80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ac90 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
1aca0 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
1acb0 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  fied.** METHOD: 
1acc0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1acd0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
1ace0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
1acf0 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64  of rows modified
1ad00 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a  , inserted or.**
1ad10 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
1ad20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
1ad30 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20  mpleted INSERT, 
1ad40 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
1ad50 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e  .** statement on
1ad60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1ad70 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69  nnection specifi
1ad80 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70  ed by the only p
1ad90 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78  arameter..** ^Ex
1ada0 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65  ecuting any othe
1adb0 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74  r type of SQL st
1adc0 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
1add0 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75   modify the valu
1ade0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
1adf0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
1ae00 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e  **.** ^Only chan
1ae10 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c  ges made directl
1ae20 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c  y by the INSERT,
1ae30 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
1ae40 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a  E statement are.
1ae50 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20  ** considered - 
1ae60 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  auxiliary change
1ae70 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 52 45  s caused by [CRE
1ae80 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
1ae90 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f  iggers], .** [fo
1aea0 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
1aeb0 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20  s] or [REPLACE] 
1aec0 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
1aed0 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f  ution are not co
1aee0 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68  unted..** .** Ch
1aef0 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
1af00 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65  that are interce
1af10 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53  pted by .** [INS
1af20 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20  TEAD OF trigger 
1af30 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  | INSTEAD OF tri
1af40 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63  ggers] are not c
1af50 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c  ounted. ^The val
1af60 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ue .** returned 
1af70 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  by sqlite3_chang
1af80 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79  es() immediately
1af90 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54   after an INSERT
1afa0 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20  , UPDATE or .** 
1afb0 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
1afc0 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69   run on a view i
1afd0 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f  s always zero. O
1afe0 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65  nly changes made
1aff0 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62   to real .** tab
1b000 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  les are counted.
1b010 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72  .**.** Things ar
1b020 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74  e more complicat
1b030 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 74 65  ed if the sqlite
1b040 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  3_changes() func
1b050 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75  tion is.** execu
1b060 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 69 67  ted while a trig
1b070 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72  ger program is r
1b080 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79  unning. This may
1b090 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a   happen if the.*
1b0a0 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74  * program uses t
1b0b0 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
1b0c0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20  L function], or 
1b0d0 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61  if some other ca
1b0e0 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
1b0f0 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74  on invokes sqlit
1b100 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72  e3_changes() dir
1b110 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c  ectly. Essential
1b120 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a  ly:.** .** <ul>.
1b130 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f  **   <li> ^(Befo
1b140 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72  re entering a tr
1b150 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68  igger program th
1b160 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1b170 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71   by.**        sq
1b180 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
1b190 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65  function is save
1b1a0 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 72 69  d. After the tri
1b1b0 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a  gger program .**
1b1c0 20 20 20 20 20 20 20 20 68 61 73 20 66 69 6e 69          has fini
1b1d0 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e  shed, the origin
1b1e0 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73 74  al value is rest
1b1f0 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20  ored.)^.** .**  
1b200 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61   <li> ^(Within a
1b210 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1b220 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50   each INSERT, UP
1b230 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20  DATE and DELETE 
1b240 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74 65  .**        state
1b250 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 76 61  ment sets the va
1b260 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1b270 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1b280 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f  ) .**        upo
1b290 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20  n completion as 
1b2a0 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73  normal. Of cours
1b2b0 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77 69  e, this value wi
1b2c0 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a  ll not include .
1b2d0 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63 68  **        any ch
1b2e0 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20  anges performed 
1b2f0 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c  by sub-triggers,
1b300 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f   as the sqlite3_
1b310 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20  changes() .**   
1b320 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20       value will 
1b330 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 65 73  be saved and res
1b340 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 63 68  tored after each
1b350 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61 73   sub-trigger has
1b360 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e   run.)^.** </ul>
1b370 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65  .** .** ^This me
1b380 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 65 20  ans that if the 
1b390 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1b3a0 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c  nction (or simil
1b3b0 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62  ar) is used.** b
1b3c0 79 20 74 68 65 20 66 69 72 73 74 20 49 4e 53 45  y the first INSE
1b3d0 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
1b3e0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
1b3f0 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c  ithin a trigger,
1b400 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20   it .** returns 
1b410 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 65 74  the value as set
1b420 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e   when the callin
1b430 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61  g statement bega
1b440 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  n executing..** 
1b450 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 20 62  ^If it is used b
1b460 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20  y the second or 
1b470 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 68 20  subsequent such 
1b480 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
1b490 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70   a trigger .** p
1b4a0 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75  rogram, the valu
1b4b0 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65  e returned refle
1b4c0 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  cts the number o
1b4d0 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20  f rows modified 
1b4e0 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69  by the .** previ
1b4f0 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ous INSERT, UPDA
1b500 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
1b510 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
1b520 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
1b530 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
1b540 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
1b550 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  l_changes()] int
1b560 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
1b570 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
1b580 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
1b590 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1b5a0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
1b5b0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
1b5c0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
1b5d0 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
1b5e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b5f0 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
1b600 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
1b610 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
1b620 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1b630 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63  d.** is unpredic
1b640 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
1b650 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
1b660 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1b670 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1b680 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
1b690 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
1b6a0 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45  s Modified.** ME
1b6b0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1b6c0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
1b6d0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74  on returns the t
1b6e0 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72  otal number of r
1b6f0 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f  ows inserted, mo
1b700 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c  dified or.** del
1b710 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53  eted by all [INS
1b720 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f  ERT], [UPDATE] o
1b730 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
1b740 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a  ments completed.
1b750 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74  ** since the dat
1b760 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b770 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63   was opened, inc
1b780 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65  luding those exe
1b790 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74  cuted as.** part
1b7a0 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67   of trigger prog
1b7b0 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67  rams. ^Executing
1b7c0 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
1b7d0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
1b7e0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66  .** does not aff
1b7f0 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65  ect the value re
1b800 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1b810 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1b820 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67  )..** .** ^Chang
1b830 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  es made as part 
1b840 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  of [foreign key 
1b850 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63  actions] are inc
1b860 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  luded in the.** 
1b870 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65  count, but those
1b880 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
1b890 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
1b8a0 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
1b8b0 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e  re.** not. ^Chan
1b8c0 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
1b8d0 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74  at are intercept
1b8e0 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46  ed by INSTEAD OF
1b8f0 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72   triggers .** ar
1b900 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
1b910 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  * .** See also t
1b920 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
1b930 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
1b940 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
1b950 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
1b960 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
1b970 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1b980 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
1b990 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
1b9a0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
1b9b0 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
1b9c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b9d0 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
1b9e0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1b9f0 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
1ba00 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
1ba10 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
1ba20 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
1ba30 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
1ba40 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
1ba50 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
1ba60 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1ba70 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
1ba80 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
1ba90 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f  g Query.** METHO
1baa0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1bab0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
1bac0 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
1bad0 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
1bae0 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
1baf0 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
1bb00 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
1bb10 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72  ortunity. This r
1bb20 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61  outine is typica
1bb30 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e  lly.** called in
1bb40 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75   response to a u
1bb50 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20  ser action such 
1bb60 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e  as pressing "Can
1bb70 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d  cel".** or Ctrl-
1bb80 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72  C where the user
1bb90 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75   wants a long qu
1bba0 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ery operation to
1bbb0 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61   halt.** immedia
1bbc0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  tely..**.** ^It 
1bbd0 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
1bbe0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
1bbf0 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
1bc00 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
1bc10 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
1bc20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
1bc30 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
1bc40 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
1bc50 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
1bc60 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
1bc70 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
1bc80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1bc90 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
1bca0 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
1bcb0 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
1bcc0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
1bcd0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  eturns..**.** ^I
1bce0 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  f an SQL operati
1bcf0 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c  on is very nearl
1bd00 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68  y finished at th
1bd10 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73  e time when.** s
1bd20 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1bd30 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  () is called, th
1bd40 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20  en it might not 
1bd50 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e  have an opportun
1bd60 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74  ity.** to be int
1bd70 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67  errupted and mig
1bd80 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63  ht continue to c
1bd90 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
1bda0 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69   ^An SQL operati
1bdb0 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
1bdc0 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
1bdd0 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
1bde0 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  RUPT]..** ^If th
1bdf0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51  e interrupted SQ
1be00 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  L operation is a
1be10 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
1be20 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
1be30 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
1be40 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
1be50 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ction, then the 
1be60 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69  entire transacti
1be70 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f  on.** will be ro
1be80 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
1be90 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  tically..**.** ^
1bea0 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  The sqlite3_inte
1beb0 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73  rrupt(D) call is
1bec0 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c   in effect until
1bed0 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72   all currently r
1bee0 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
1bef0 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74  atements on [dat
1bf00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1bf10 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  ] D complete.  ^
1bf20 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74  Any new SQL stat
1bf30 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
1bf40 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
1bf50 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1bf60 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e  errupt() call an
1bf70 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a  d before the .**
1bf80 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
1bf90 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f  nts reaches zero
1bfa0 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64   are interrupted
1bfb0 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20   as if they had 
1bfc0 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  been.** running 
1bfd0 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c  prior to the sql
1bfe0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1bff0 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c   call.  ^New SQL
1c000 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1c010 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1c020 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e  after the runnin
1c030 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e  g statement coun
1c040 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  t reaches zero a
1c050 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74  re.** not effect
1c060 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
1c070 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a  3_interrupt()..*
1c080 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  * ^A call to sql
1c090 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
1c0a0 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68  ) that occurs wh
1c0b0 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  en there are no 
1c0c0 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
1c0d0 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e  tatements is a n
1c0e0 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20  o-op and has no 
1c0f0 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
1c100 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1c110 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1c120 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
1c130 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
1c140 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76 6f 69 64  returns..*/.void
1c150 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1c160 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  pt(sqlite3*);../
1c170 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
1c180 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
1c190 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20  QL Statement Is 
1c1a0 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54  Complete.**.** T
1c1b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1c1c0 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20  e useful during 
1c1d0 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70  command-line inp
1c1e0 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ut to determine 
1c1f0 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  if the.** curren
1c200 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74  tly entered text
1c210 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61   seems to form a
1c220 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
1c230 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66  atement or.** if
1c240 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75   additional inpu
1c250 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f  t is needed befo
1c260 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74  re sending the t
1c270 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69  ext into.** SQLi
1c280 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20  te for parsing. 
1c290 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1c2a0 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65   return 1 if the
1c2b0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a   input string.**
1c2c0 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61   appears to be a
1c2d0 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
1c2e0 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61  atement.  ^A sta
1c2f0 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64  tement is judged
1c300 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65   to be.** comple
1c310 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69  te if it ends wi
1c320 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74  th a semicolon t
1c330 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20  oken and is not 
1c340 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a  a prefix of a.**
1c350 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45   well-formed CRE
1c360 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
1c370 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c  ement.  ^Semicol
1c380 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62  ons that are emb
1c390 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  edded within.** 
1c3a0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20  string literals 
1c3b0 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69  or quoted identi
1c3c0 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f  fier names or co
1c3d0 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a  mments are not.*
1c3e0 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f  * independent to
1c3f0 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70  kens (they are p
1c400 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e  art of the token
1c410 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61   in which they a
1c420 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20  re.** embedded) 
1c430 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20  and thus do not 
1c440 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65  count as a state
1c450 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e  ment terminator.
1c460 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a    ^Whitespace.**
1c470 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68   and comments th
1c480 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69  at follow the fi
1c490 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72  nal semicolon ar
1c4a0 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  e ignored..**.**
1c4b0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1c4c0 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65   return 0 if the
1c4d0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e   statement is in
1c4e0 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61  complete.  ^If a
1c4f0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
1c500 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65  ation fails, the
1c510 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69  n SQLITE_NOMEM i
1c520 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
1c530 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
1c540 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74  s do not parse t
1c550 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1c560 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e  s thus.** will n
1c570 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63  ot detect syntac
1c580 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63  tically incorrec
1c590 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  t SQL..**.** ^(I
1c5a0 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74  f SQLite has not
1c5b0 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65   been initialize
1c5c0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1c5d0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70  _initialize()] p
1c5e0 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f  rior .** to invo
1c5f0 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d  king sqlite3_com
1c600 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73  plete16() then s
1c610 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
1c620 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
1c630 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
1c640 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  by sqlite3_compl
1c650 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61  ete16().  If tha
1c660 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  t initialization
1c670 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20   fails,.** then 
1c680 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1c690 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
1c6a0 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20  mplete16() will 
1c6b0 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72  be non-zero.** r
1c6c0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1c6d0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
1c6e0 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d  input SQL is com
1c6f0 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  plete.)^.**.** T
1c700 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
1c710 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d  ite3_complete()]
1c720 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
1c730 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
1c740 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  F-8 string..**.*
1c750 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
1c760 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1c770 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  16()] must be a 
1c780 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1c790 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
1c7a0 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
1c7b0 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  order..*/.int sq
1c7c0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63  lite3_complete(c
1c7d0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b  onst char *sql);
1c7e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
1c7f0 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
1c800 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
1c810 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
1c820 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
1c830 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
1c840 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b  BUSY Errors.** K
1c850 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68  EYWORDS: {busy-h
1c860 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d  andler callback}
1c870 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a   {busy handler}.
1c880 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1c890 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
1c8a0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1c8b0 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e  er(D,X,P) routin
1c8c0 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
1c8d0 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20  k function X.** 
1c8e0 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
1c8f0 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d  voked with argum
1c900 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a  ent P whenever.*
1c910 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
1c920 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 61  made to access a
1c930 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
1c940 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
1c950 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1c960 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20  nection] D when 
1c970 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
1c980 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
1c990 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65   the table locke
1c9a0 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  d..** The sqlite
1c9b0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1c9c0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
1c9d0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a  ed to implement.
1c9e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
1c9f0 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20  _timeout()] and 
1ca00 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
1ca10 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  eout]..**.** ^If
1ca20 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
1ca30 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
1ca40 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
1ca50 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
1ca60 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
1ca70 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
1ca80 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
1ca90 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
1caa0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
1cab0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
1cac0 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
1cad0 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
1cae0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
1caf0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1cb00 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1cb10 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
1cb20 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
1cb30 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
1cb40 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1cb50 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
1cb60 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
1cb70 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1cb80 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
1cb90 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
1cba0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
1cbb0 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
1cbc0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
1cbd0 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
1cbe0 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72  d previously for
1cbf0 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e   the same lockin
1cc00 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
1cc10 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
1cc20 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
1cc30 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
1cc40 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
1cc50 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
1cc60 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
1cc70 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69   [SQLITE_BUSY] i
1cc80 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f  s returned.** to
1cc90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1cca0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
1ccb0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
1ccc0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
1ccd0 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
1cce0 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
1ccf0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
1cd00 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70  nd the cycle rep
1cd10 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eats..**.** The 
1cd20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75  presence of a bu
1cd30 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20  sy handler does 
1cd40 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68  not guarantee th
1cd50 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  at it will be in
1cd60 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68  voked.** when th
1cd70 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74  ere is lock cont
1cd80 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69  ention. ^If SQLi
1cd90 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
1cda0 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
1cdb0 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
1cdc0 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
1cdd0 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
1cde0 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
1cdf0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1ce00 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  BUSY].** to the 
1ce10 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74  application inst
1ce20 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
1ce30 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e  the .** busy han
1ce40 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
1ce50 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
1ce60 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
1ce70 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
1ce80 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
1ce90 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
1cea0 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
1ceb0 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
1cec0 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
1ced0 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
1cee0 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
1cef0 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
1cf00 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
1cf10 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
1cf20 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
1cf30 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
1cf40 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
1cf50 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1cf60 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
1cf70 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
1cf80 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
1cf90 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
1cfa0 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
1cfb0 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
1cfc0 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
1cfd0 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
1cfe0 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
1cff0 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
1d000 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
1d010 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
1d020 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
1d030 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
1d040 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
1d050 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
1d060 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
1d070 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
1d080 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
1d090 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
1d0a0 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
1d0b0 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
1d0c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
1d0d0 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
1d0e0 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
1d0f0 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
1d100 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
1d110 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
1d120 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ned for each.** 
1d130 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1d140 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20  tion].  Setting 
1d150 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
1d160 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a  er clears any.**
1d170 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
1d180 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74  handler.)^  ^Not
1d190 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
1d1a0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1d1b0 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76  eout()].** or ev
1d1c0 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41  aluating [PRAGMA
1d1d0 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d   busy_timeout=N]
1d1e0 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65   will change the
1d1f0 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72  .** busy handler
1d200 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20   and thus clear 
1d210 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73  any previously s
1d220 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  et busy handler.
1d230 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20  .**.** The busy 
1d240 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20  callback should 
1d250 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74  not take any act
1d260 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66  ions which modif
1d270 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  y the.** databas
1d280 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1d290 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
1d2a0 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20  sy handler.  In 
1d2b0 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20  other words,.** 
1d2c0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1d2d0 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
1d2e0 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  t.  Any such act
1d2f0 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
1d300 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
1d310 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
1d320 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
1d330 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
1d340 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d350 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
1d360 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
1d370 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
1d380 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
1d390 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
1d3a0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
1d3b0 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  *,int(*)(void*,i
1d3c0 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  nt),void*);../*.
1d3d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
1d3e0 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
1d3f0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1d400 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  e3.**.** ^This r
1d410 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
1d420 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1d430 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
1d440 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
1d450 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
1d460 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
1d470 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
1d480 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20  s locked.  ^The 
1d490 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20  handler.** will 
1d4a0 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
1d4b0 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65  imes until at le
1d4c0 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
1d4d0 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
1d4e0 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75  g.** have accumu
1d4f0 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61  lated.  ^After a
1d500 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
1d510 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
1d520 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61  eping,.** the ha
1d530 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20  ndler returns 0 
1d540 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71  which causes [sq
1d550 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
1d560 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
1d570 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_BUSY]..**.** 
1d580 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f  ^Calling this ro
1d590 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
1d5a0 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
1d5b0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
1d5c0 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
1d5d0 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
1d5e0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
1d5f0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
1d600 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
1d610 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
1d620 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
1d630 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61  connection] at a
1d640 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
1d650 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
1d660 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
1d670 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
1d680 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1d690 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
1d6a0 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
1d6b0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
1d6c0 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
1d6d0 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
1d6e0 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
1d6f0 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79  o:  [PRAGMA busy
1d700 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74  _timeout].*/.int
1d710 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
1d720 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
1d730 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
1d740 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
1d750 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
1d760 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
1d770 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
1d780 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73  lite3.**.** This
1d790 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74   is a legacy int
1d7a0 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70  erface that is p
1d7b0 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63  reserved for bac
1d7c0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1d7d0 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20  lity..** Use of 
1d7e0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
1d7f0 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65  s not recommende
1d800 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  d..**.** Definit
1d810 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
1d820 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
1d830 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
1d840 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
1d850 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
1d860 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
1d870 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
1d880 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
1d890 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
1d8a0 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
1d8b0 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
1d8c0 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
1d8d0 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
1d8e0 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
1d8f0 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
1d900 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
1d910 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
1d920 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
1d930 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
1d940 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
1d950 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
1d960 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
1d970 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
1d980 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
1d990 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
1d9a0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
1d9b0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
1d9c0 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
1d9d0 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
1d9e0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1d9f0 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
1da00 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
1da10 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
1da20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
1da30 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
1da40 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
1da50 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1da60 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
1da70 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
1da80 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
1da90 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
1daa0 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
1dab0 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
1dac0 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
1dad0 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
1dae0 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
1daf0 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
1db00 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
1db10 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1db20 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
1db30 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
1db40 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1db50 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
1db60 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1db70 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
1db80 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
1db90 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
1dba0 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
1dbb0 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
1dbc0 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1dbd0 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
1dbe0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
1dbf0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1dc00 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
1dc10 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
1dc20 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1dc30 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61  )]..**.** ^(As a
1dc40 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
1dc50 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
1dc60 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
1dc70 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
1dc80 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1dc90 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1dca0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1dcb0 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
1dcc0 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
1dcd0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1dce0 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
1dcf0 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
1dd00 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
1dd10 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
1dd20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
1dd30 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
1dd40 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1dd50 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
1dd60 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
1dd70 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
1dd80 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
1dd90 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
1dda0 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
1ddb0 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
1ddc0 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
1ddd0 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
1dde0 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
1ddf0 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
1de00 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
1de10 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
1de20 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1de30 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1de40 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
1de50 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1de60 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
1de70 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1de80 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
1de90 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
1dea0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1deb0 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
1dec0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1ded0 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
1dee0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1def0 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
1df00 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1df10 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
1df20 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
1df30 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
1df40 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
1df50 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
1df60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1df70 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
1df80 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
1df90 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
1dfa0 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
1dfb0 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
1dfc0 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
1dfd0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1dfe0 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
1dff0 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  s 2nd parameter 
1e000 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65  and returns a re
1e010 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
1e020 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
1e030 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
1e040 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
1e050 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  fter the applica
1e060 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
1e070 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c  d with the resul
1e080 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67  t from sqlite3_g
1e090 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69  et_table(),.** i
1e0a0 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20  t must pass the 
1e0b0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69  result table poi
1e0c0 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
1e0d0 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
1e0e0 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
1e0f0 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
1e100 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
1e110 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
1e120 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
1e130 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1e140 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
1e150 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1e160 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
1e170 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
1e180 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
1e190 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1e1a0 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
1e1b0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
1e1c0 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
1e1d0 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
1e1e0 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
1e1f0 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
1e200 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1e210 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
1e220 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
1e230 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
1e240 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
1e250 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
1e260 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1e270 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
1e280 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
1e290 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
1e2a0 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
1e2b0 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
1e2c0 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
1e2d0 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
1e2e0 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
1e2f0 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
1e300 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
1e310 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
1e320 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
1e330 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
1e340 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
1e350 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
1e360 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
1e370 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
1e380 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
1e390 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1e3a0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1e3b0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69  _errmsg()]..*/.i
1e3c0 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
1e3d0 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
1e3e0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
1e3f0 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
1e400 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1e410 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
1e420 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
1e430 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
1e440 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
1e450 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
1e460 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
1e470 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
1e480 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1e490 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
1e4a0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
1e4b0 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
1e4c0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1e4d0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
1e4e0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1e4f0 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
1e500 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
1e510 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
1e520 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69   */.);.void sqli
1e530 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
1e540 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
1e550 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e560 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
1e570 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
1e580 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
1e590 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
1e5a0 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  k-alikes of the 
1e5b0 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
1e5c0 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
1e5d0 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
1e5e0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
1e5f0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1e600 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74   understand most
1e610 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b   of the common K
1e620 26 52 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  &R formatting op
1e630 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73  tions,.** plus s
1e640 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e  ome additional n
1e650 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d  on-standard form
1e660 61 74 73 2c 20 64 65 74 61 69 6c 65 64 20 62 65  ats, detailed be
1e670 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  low..** Note tha
1e680 74 20 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f  t some of the mo
1e690 72 65 20 6f 62 73 63 75 72 65 20 66 6f 72 6d 61  re obscure forma
1e6a0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72  tting options fr
1e6b0 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c  om recent.** C-l
1e6c0 69 62 72 61 72 79 20 73 74 61 6e 64 61 72 64 73  ibrary standards
1e6d0 20 61 72 65 20 6f 6d 69 74 74 65 64 20 66 72 6f   are omitted fro
1e6e0 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74  m this implement
1e6f0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
1e700 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
1e710 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
1e720 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
1e730 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
1e740 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
1e750 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
1e760 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
1e770 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
1e780 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
1e790 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
1e7a0 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
1e7b0 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
1e7c0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1e7d0 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65  .  ^Both routine
1e7e0 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55  s return a.** NU
1e7f0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73  LL pointer if [s
1e800 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1e810 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1e820 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
1e830 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
1e840 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
1e850 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ring..**.** ^(Th
1e860 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  e sqlite3_snprin
1e870 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1e880 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
1e890 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
1e8a0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1e8b0 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
1e8c0 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
1e8d0 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
1e8e0 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
1e8f0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1e900 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
1e910 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
1e920 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1e930 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
1e940 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
1e950 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
1e960 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
1e970 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
1e980 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  .)^  This is an.
1e990 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
1e9a0 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
1e9b0 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
1e9c0 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
1e9d0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1e9e0 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65  ibility.  ^(Note
1e9f0 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
1ea00 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1ea10 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1ea20 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
1ea30 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1ea40 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
1ea50 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
1ea60 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1ea70 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20  e buffer.)^  We 
1ea80 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
1ea90 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
1eaa0 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
1eab0 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
1eac0 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
1ead0 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
1eae0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
1eaf0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1eb00 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1eb10 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
1eb20 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
1eb30 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
1eb40 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65   ^As long as the
1eb50 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
1eb60 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
1eb70 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
1eb80 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
1eb90 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
1eba0 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
1ebb0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
1ebc0 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61  ^The first.** pa
1ebd0 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
1ebe0 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
1ebf0 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
1ec00 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
1ec10 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
1ec20 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
1ec30 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
1ec40 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
1ec50 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
1ec60 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
1ec70 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
1ec80 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e  ^The sqlite3_vsn
1ec90 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1eca0 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65   is a varargs ve
1ecb0 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  rsion of sqlite3
1ecc0 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a  _snprintf()..**.
1ecd0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1ece0 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20  s all implement 
1ecf0 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
1ed00 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70  formatting.** op
1ed10 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75  tions that are u
1ed20 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72  seful for constr
1ed30 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  ucting SQL state
1ed40 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66  ments..** All of
1ed50 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74   the usual print
1ed60 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  f() formatting o
1ed70 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49  ptions apply.  I
1ed80 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
1ed90 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22  e.** is are "%q"
1eda0 2c 20 22 25 51 22 2c 20 22 25 77 22 20 61 6e 64  , "%Q", "%w" and
1edb0 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a   "%z" options..*
1edc0 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70  *.** ^(The %q op
1edd0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1ede0 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
1edf0 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d  bstitutes a nul-
1ee00 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
1ee10 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72  ring from the ar
1ee20 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75  gument list.  Bu
1ee30 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65  t %q also double
1ee40 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61  s every '\'' cha
1ee50 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73  racter..** %q is
1ee60 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73   designed for us
1ee70 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e  e inside a strin
1ee80 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79  g literal.)^  By
1ee90 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27   doubling each '
1eea0 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  \''.** character
1eeb0 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74   it escapes that
1eec0 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61   character and a
1eed0 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69  llows it to be i
1eee0 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20  nserted into.** 
1eef0 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  the string..**.*
1ef00 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61  * For example, a
1ef10 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67  ssume the string
1ef20 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20   variable zText 
1ef30 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73  contains text as
1ef40 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1ef50 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1ef60 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78  >.**  char *zTex
1ef70 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70  t = "It's a happ
1ef80 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72  y day!";.** </pr
1ef90 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1efa0 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73  **.** One can us
1efb0 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61  e this text in a
1efc0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1efd0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1efe0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1eff0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
1f000 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
1f010 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
1f020 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27  O table VALUES('
1f030 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  %q')", zText);.*
1f040 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1f050 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1f060 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1f070 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1f080 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1f090 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  e>.**.** Because
1f0a0 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73   the %q format s
1f0b0 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  tring is used, t
1f0c0 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  he '\'' characte
1f0d0 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73  r in zText.** is
1f0e0 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65   escaped and the
1f0f0 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69   SQL generated i
1f100 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
1f110 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1f120 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
1f130 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
1f140 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70  UES('It''s a hap
1f150 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70  py day!').** </p
1f160 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1f170 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63  .**.** This is c
1f180 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20  orrect.  Had we 
1f190 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20  used %s instead 
1f1a0 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72  of %q, the gener
1f1b0 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c  ated SQL.** woul
1f1c0 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69  d have looked li
1f1d0 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
1f1e0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1f1f0 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1f200 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1f210 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1f220 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  !');.** </pre></
1f230 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1f240 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78  * This second ex
1f250 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20  ample is an SQL 
1f260 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41  syntax error.  A
1f270 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65  s a general rule
1f280 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61   you should.** a
1f290 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73  lways use %q ins
1f2a0 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20  tead of %s when 
1f2b0 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69  inserting text i
1f2c0 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74  nto a string lit
1f2d0 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  eral..**.** ^(Th
1f2e0 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %Q option work
1f2f0 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74  s like %q except
1f300 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69   it also adds si
1f310 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75  ngle quotes arou
1f320 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64  nd.** the outsid
1f330 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73  e of the total s
1f340 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  tring.  Addition
1f350 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72  ally, if the par
1f360 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a  ameter in the.**
1f370 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69   argument list i
1f380 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1f390 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73  , %Q substitutes
1f3a0 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22   the text "NULL"
1f3b0 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e   (without.** sin
1f3c0 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20  gle quotes).)^  
1f3d0 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  So, for example,
1f3e0 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a   one could say:.
1f3f0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1f400 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1f410 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
1f420 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
1f430 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
1f440 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b  ES(%Q)", zText);
1f450 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
1f460 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
1f470 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
1f480 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
1f490 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1f4a0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ote>.**.** The c
1f4b0 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72  ode above will r
1f4c0 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20  ender a correct 
1f4d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1f4e0 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72   the zSQL.** var
1f4f0 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68  iable even if th
1f500 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65  e zText variable
1f510 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1f520 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  er..**.** ^(The 
1f530 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%w" formatting 
1f540 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22  option is like "
1f550 25 71 22 20 65 78 63 65 70 74 20 74 68 61 74 20  %q" except that 
1f560 69 74 20 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a  it expects to.**
1f570 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 77 69   be contained wi
1f580 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74  thin double-quot
1f590 65 73 20 69 6e 73 74 65 61 64 20 6f 66 20 73 69  es instead of si
1f5a0 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e 64  ngle quotes, and
1f5b0 20 69 74 0a 2a 2a 20 65 73 63 61 70 65 73 20 74   it.** escapes t
1f5c0 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20  he double-quote 
1f5d0 63 68 61 72 61 63 74 65 72 20 69 6e 73 74 65 61  character instea
1f5e0 64 20 6f 66 20 74 68 65 20 73 69 6e 67 6c 65 2d  d of the single-
1f5f0 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63 74  quote.** charact
1f600 65 72 2e 29 5e 20 20 54 68 65 20 22 25 77 22 20  er.)^  The "%w" 
1f610 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1f620 6e 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  n is intended fo
1f630 72 20 73 61 66 65 6c 79 20 69 6e 73 65 72 74 69  r safely inserti
1f640 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20  ng.** table and 
1f650 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74  column names int
1f660 6f 20 61 20 63 6f 6e 73 74 72 75 63 74 65 64 20  o a constructed 
1f670 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
1f680 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20  *.** ^(The "%z" 
1f690 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1f6a0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73  n works like "%s
1f6b0 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a  " but with the.*
1f6c0 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  * addition that 
1f6d0 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67  after the string
1f6e0 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61   has been read a
1f6f0 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a  nd copied into.*
1f700 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73  * the result, [s
1f710 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69  qlite3_free()] i
1f720 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20  s called on the 
1f730 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a  input string.)^.
1f740 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  */.char *sqlite3
1f750 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
1f760 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20  har*,...);.char 
1f770 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
1f780 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
1f790 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73  a_list);.char *s
1f7a0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1f7b0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1f7c0 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61  char*, ...);.cha
1f7d0 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  r *sqlite3_vsnpr
1f7e0 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1f7f0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1f800 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ist);../*.** CAP
1f810 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
1f820 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
1f830 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  em.**.** The SQL
1f840 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
1f850 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
1f860 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
1f870 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
1f880 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
1f890 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
1f8a0 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
1f8b0 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
1f8c0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
1f8d0 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
1f8e0 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
1f8f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
1f900 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
1f910 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
1f920 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
1f930 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
1f940 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions..**.** ^The
1f950 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1f960 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
1f970 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1f980 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
1f990 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
1f9a0 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
1f9b0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
1f9c0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
1f9d0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1f9e0 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
1f9f0 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
1fa00 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
1fa10 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
1fa20 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66  LL pointer.  ^If
1fa30 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
1fa40 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
1fa50 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
1fa60 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
1fa70 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1fa80 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
1fa90 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1faa0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1fab0 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74  malloc64(N) rout
1fac0 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c  ine works just l
1fad0 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ike.** sqlite3_m
1fae0 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20  alloc(N) except 
1faf0 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73  that N is an uns
1fb00 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74  igned 64-bit int
1fb10 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  eger instead.** 
1fb20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62  of a signed 32-b
1fb30 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  it integer..**.*
1fb40 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
1fb50 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
1fb60 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
1fb70 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
1fb80 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1fb90 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1fba0 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
1fbb0 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
1fbc0 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
1fbd0 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
1fbe0 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
1fbf0 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
1fc00 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
1fc10 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
1fc20 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
1fc30 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
1fc40 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
1fc50 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
1fc60 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
1fc70 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
1fc80 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
1fc90 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
1fca0 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
1fcb0 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
1fcc0 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
1fcd0 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
1fce0 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1fcf0 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
1fd00 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
1fd10 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
1fd20 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1fd30 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
1fd40 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
1fd50 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
1fd60 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1fd70 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1fd80 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
1fd90 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
1fda0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
1fdb0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1fdc0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1fdd0 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  oc()..**.** ^The
1fde0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1fdf0 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (X,N) interface 
1fe00 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
1fe10 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
1fe20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1fe30 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  X to be at least
1fe40 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66   N bytes..** ^If
1fe50 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72   the X parameter
1fe60 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1fe70 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61  loc(X,N).** is a
1fe80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
1fe90 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20  en its behavior 
1fea0 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
1feb0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1fec0 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a  e3_malloc(N)..**
1fed0 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d   ^If the N param
1fee0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1fef0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20  realloc(X,N) is 
1ff00 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
1ff10 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
1ff20 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
1ff30 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
1ff40 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
1ff50 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c  free(X)..** ^sql
1ff60 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1ff70 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
1ff80 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
1ff90 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
1ffa0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1ffb0 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
1ffc0 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e  L if insufficien
1ffd0 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69  t memory is avai
1ffe0 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
1fff0 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
20000 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
20010 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
20020 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
20030 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
20040 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
20050 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
20060 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
20070 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
20080 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
20090 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
200a0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
200b0 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
200c0 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72  3_realloc(X,N) r
200d0 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20  eturns NULL and 
200e0 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74  N is positive, t
200f0 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72  hen the.** prior
20100 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e   allocation is n
20110 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
20120 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  ^The sqlite3_rea
20130 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65  lloc64(X,N) inte
20140 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65  rfaces works the
20150 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69   same as.** sqli
20160 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
20170 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
20180 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67  s a 64-bit unsig
20190 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74  ned integer inst
201a0 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62  ead.** of a 32-b
201b0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
201c0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69  r..**.** ^If X i
201d0 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  s a memory alloc
201e0 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79  ation previously
201f0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
20200 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c  qlite3_malloc(),
20210 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
20220 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f  oc64(), sqlite3_
20230 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71  realloc(), or sq
20240 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
20250 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  ), then.** sqlit
20260 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75  e3_msize(X) retu
20270 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
20280 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  that memory allo
20290 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e  cation in bytes.
202a0 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72  .** ^The value r
202b0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
202c0 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68  e3_msize(X) migh
202d0 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  t be larger than
202e0 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f   the number.** o
202f0 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74 65  f bytes requeste
20300 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c  d when X was all
20310 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69  ocated.  ^If X i
20320 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
20330 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
20340 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e  _msize(X) return
20350 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f  s zero.  If X po
20360 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e  ints to somethin
20370 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a  g that is not.**
20380 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
20390 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
203a0 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f  ion, or if it po
203b0 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72  ints to a former
203c0 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f  ly.** valid memo
203d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68  ry allocation th
203e0 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20  at has now been 
203f0 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20  freed, then the 
20400 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73  behavior.** of s
20410 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
20420 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
20430 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75   possibly harmfu
20440 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
20450 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
20460 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
20470 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
20480 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  oc(),.** sqlite3
20490 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64  _malloc64(), and
204a0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
204b0 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  64().** is alway
204c0 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
204d0 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
204e0 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20  boundary, or to 
204f0 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e  a.** 4 byte boun
20500 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c  dary if the [SQL
20510 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e  ITE_4_BYTE_ALIGN
20520 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69  ED_MALLOC] compi
20530 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
20540 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
20550 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
20560 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
20570 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
20580 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
20590 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
205a0 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
205b0 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
205c0 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
205d0 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
205e0 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
205f0 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
20600 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
20610 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
20620 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
20630 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
20640 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
20650 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
20660 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
20670 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
20680 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20  10, the Windows 
20690 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
206a0 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65  er called.** the
206b0 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
206c0 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
206d0 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
206e0 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
206f0 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
20700 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
20710 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
20720 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
20730 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
20740 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
20750 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
20760 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
20770 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
20780 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20  ion errors were 
20790 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
207a0 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72   they were repor
207b0 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c  ted back as [SQL
207c0 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72  ITE_CANTOPEN] or
207d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
207e0 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b  R] rather than [
207f0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
20800 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
20810 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
20820 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
20830 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
20840 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  loc()].** must b
20850 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
20860 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
20870 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
20880 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  rior.** invocati
20890 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
208a0 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
208b0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
208c0 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74  that have.** not
208d0 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
208e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  ed..**.** The ap
208f0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
20900 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
20910 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
20920 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
20930 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
20940 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
20950 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
20960 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
20970 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
20980 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
20990 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  malloc(int);.voi
209a0 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
209b0 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74  c64(sqlite3_uint
209c0 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  64);.void *sqlit
209d0 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
209e0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  , int);.void *sq
209f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
20a00 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75  void*, sqlite3_u
20a10 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
20a20 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
20a30 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  ;.sqlite3_uint64
20a40 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76   sqlite3_msize(v
20a50 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
20a60 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
20a70 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74  llocator Statist
20a80 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ics.**.** SQLite
20a90 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20   provides these 
20aa0 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66  two interfaces f
20ab0 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20  or reporting on 
20ac0 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66  the status.** of
20ad0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   the [sqlite3_ma
20ae0 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
20af0 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b  3_free()], and [
20b00 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
20b10 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20  )].** routines, 
20b20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62  which form the b
20b30 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
20b40 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
20b50 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tem..**.** ^The 
20b60 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
20b70 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20  used()] routine 
20b80 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
20b90 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f  er of bytes.** o
20ba0 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74  f memory current
20bb0 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28  ly outstanding (
20bc0 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74  malloced but not
20bd0 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65   freed)..** ^The
20be0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
20bf0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f  _highwater()] ro
20c00 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
20c10 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c  e maximum.** val
20c20 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  ue of [sqlite3_m
20c30 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69  emory_used()] si
20c40 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74  nce the high-wat
20c50 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c  er mark.** was l
20c60 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65  ast reset.  ^The
20c70 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
20c80 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
20c90 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
20ca0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
20cb0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
20cc0 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72  include any over
20cd0 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79  head.** added by
20ce0 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
20cf0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
20d00 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
20d10 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ()],.** but not 
20d20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
20d30 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
20d40 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
20d50 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ary.** routines 
20d60 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61  that [sqlite3_ma
20d70 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c  lloc()] may call
20d80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
20d90 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d  ory high-water m
20da0 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20  ark is reset to 
20db0 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
20dc0 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  e of.** [sqlite3
20dd0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
20de0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
20df0 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
20e00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
20e10 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
20e20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76  is true.  ^The v
20e30 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
20e40 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
20e50 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
20e60 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61  ] is the high-wa
20e70 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f  ter mark.** prio
20e80 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a  r to the reset..
20e90 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
20ea0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
20eb0 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69  used(void);.sqli
20ec0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
20ed0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
20ee0 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
20ef0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20f00 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
20f10 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
20f20 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  or.**.** SQLite 
20f30 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
20f40 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
20f50 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
20f60 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
20f70 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
20f80 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
20f90 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
20fa0 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
20fb0 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
20fc0 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
20fd0 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
20fe0 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
20ff0 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
21000 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
21010 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
21020 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
21030 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
21040 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
21050 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
21060 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
21070 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
21080 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
21090 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
210a0 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  ^A call to this 
210b0 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
210c0 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
210d0 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
210e0 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61   P..** ^The P pa
210f0 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61  rameter can be a
21100 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
21110 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f  *.** ^If this ro
21120 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65  utine has not be
21130 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61  en previously ca
21140 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 70  lled or if the p
21150 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20  revious.** call 
21160 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20  had N less than 
21170 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  one or a NULL po
21180 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65  inter for P, the
21190 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a  n the PRNG is.**
211a0 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61   seeded using ra
211b0 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
211c0 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  d from the xRand
211d0 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
211e0 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
211f0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
21200 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ject..** ^If the
21210 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
21220 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  o this routine h
21230 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20  ad an N of 1 or 
21240 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f  more and a.** no
21250 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68  n-NULL P then th
21260 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
21270 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
21280 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
21290 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
212a0 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
212b0 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
212c0 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
212d0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
212e0 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
212f0 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
21300 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
21310 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
21320 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
21330 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
21340 69 74 65 33 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ite3.** KEYWORDS
21350 3a 20 7b 61 75 74 68 6f 72 69 7a 65 72 20 63 61  : {authorizer ca
21360 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a 20 5e 54  llback}.**.** ^T
21370 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
21380 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69  sters an authori
21390 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74  zer callback wit
213a0 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
213b0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
213c0 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65  ection], supplie
213d0 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
213e0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
213f0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21400 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
21410 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
21420 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
21430 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
21440 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
21450 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
21460 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21470 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
21480 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
21490 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
214a0 72 65 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  re16()], [sqlite
214b0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
214c0 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  ],.** and [sqlit
214d0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
214e0 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73  )].  ^At various
214f0 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e  .** points durin
21500 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f  g the compilatio
21510 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f  n process, as lo
21520 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65  gic is being cre
21530 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f  ated.** to perfo
21540 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f  rm various actio
21550 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ns, the authoriz
21560 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
21570 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65  nvoked to.** see
21580 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e   if those action
21590 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20  s are allowed.  
215a0 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
215b0 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a  callback should.
215c0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
215d0 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74  E_OK] to allow t
215e0 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49  he action, [SQLI
215f0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69  TE_IGNORE] to di
21600 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70  sallow the.** sp
21610 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75  ecific action bu
21620 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20  t allow the SQL 
21630 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e  statement to con
21640 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63  tinue to be.** c
21650 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c  ompiled, or [SQL
21660 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75  ITE_DENY] to cau
21670 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51  se the entire SQ
21680 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  L statement to b
21690 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69  e.** rejected wi
216a0 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49  th an error.  ^I
216b0 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
216c0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
216d0 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f  s.** any value o
216e0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
216f0 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49  E_IGNORE], [SQLI
21700 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49  TE_OK], or [SQLI
21710 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e  TE_DENY].** then
21720 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
21730 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
21740 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
21750 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a  hat triggered.**
21760 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
21770 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
21780 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
21790 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
217a0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
217b0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
217c0 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65  at means the ope
217d0 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73  ration.** reques
217e0 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65  ted is ok.  ^Whe
217f0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
21800 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
21810 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71  ENY], the.** [sq
21820 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
21830 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
21840 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
21850 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74  gered the.** aut
21860 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
21870 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
21880 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69  message explaini
21890 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73  ng that.** acces
218a0 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a  s is denied. .**
218b0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
218c0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
218d0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
218e0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
218f0 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
21900 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
21910 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
21920 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63  rizer() interfac
21930 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  e. ^The second p
21940 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
21950 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
21960 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54  n integer [SQLIT
21970 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
21980 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
21990 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74  fies.** the part
219a0 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f  icular action to
219b0 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
219c0 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75  ^The third throu
219d0 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  gh sixth paramet
219e0 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ers.** to the ca
219f0 6c 6c 62 61 63 6b 20 61 72 65 20 65 69 74 68 65  llback are eithe
21a00 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  r NULL pointers 
21a10 6f 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  or zero-terminat
21a20 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 74 68  ed strings.** th
21a30 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
21a40 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61 62  ional details ab
21a50 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
21a60 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
21a70 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
21a80 20 6d 75 73 74 20 61 6c 77 61 79 73 20 62 65 20   must always be 
21a90 70 72 65 70 61 72 65 64 20 74 6f 20 65 6e 63 6f  prepared to enco
21aa0 75 6e 74 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  unter a NULL poi
21ab0 6e 74 65 72 20 69 6e 20 61 6e 79 0a 2a 2a 20 6f  nter in any.** o
21ac0 66 20 74 68 65 20 74 68 69 72 64 20 74 68 72 6f  f the third thro
21ad0 75 67 68 20 74 68 65 20 73 69 78 74 68 20 70 61  ugh the sixth pa
21ae0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
21af0 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61  authorization ca
21b00 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 49  llback..**.** ^I
21b10 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
21b20 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
21b30 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
21b40 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
21b50 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
21b60 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
21b70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
21b80 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
21b90 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
21ba0 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
21bb0 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
21bc0 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
21bd0 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
21be0 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
21bf0 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
21c00 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
21c10 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
21c20 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
21c30 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
21c40 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
21c50 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
21c60 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
21c70 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
21c80 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 74  le..** ^When a t
21c90 61 62 6c 65 20 69 73 20 72 65 66 65 72 65 6e 63  able is referenc
21ca0 65 64 20 62 79 20 61 20 5b 53 45 4c 45 43 54 5d  ed by a [SELECT]
21cb0 20 62 75 74 20 6e 6f 20 63 6f 6c 75 6d 6e 20 76   but no column v
21cc0 61 6c 75 65 73 20 61 72 65 0a 2a 2a 20 65 78 74  alues are.** ext
21cd0 72 61 63 74 65 64 20 66 72 6f 6d 20 74 68 61 74  racted from that
21ce0 20 74 61 62 6c 65 20 28 66 6f 72 20 65 78 61 6d   table (for exam
21cf0 70 6c 65 20 69 6e 20 61 20 71 75 65 72 79 20 6c  ple in a query l
21d00 69 6b 65 0a 2a 2a 20 22 53 45 4c 45 43 54 20 63  ike.** "SELECT c
21d10 6f 75 6e 74 28 2a 29 20 46 52 4f 4d 20 74 61 62  ount(*) FROM tab
21d20 22 29 20 74 68 65 6e 20 74 68 65 20 5b 53 51 4c  ") then the [SQL
21d30 49 54 45 5f 52 45 41 44 5d 20 61 75 74 68 6f 72  ITE_READ] author
21d40 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
21d50 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65   is invoked once
21d60 20 66 6f 72 20 74 68 61 74 20 74 61 62 6c 65 20   for that table 
21d70 77 69 74 68 20 61 20 63 6f 6c 75 6d 6e 20 6e 61  with a column na
21d80 6d 65 20 74 68 61 74 20 69 73 20 61 6e 20 65 6d  me that is an em
21d90 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  pty string..** ^
21da0 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
21db0 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45  de is [SQLITE_DE
21dc0 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61  LETE] and the ca
21dd0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
21de0 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  * [SQLITE_IGNORE
21df0 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45  ] then the [DELE
21e00 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  TE] operation pr
21e10 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a  oceeds but the.*
21e20 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  * [truncate opti
21e30 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73  mization] is dis
21e40 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f  abled and all ro
21e50 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69  ws are deleted i
21e60 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a  ndividually..**.
21e70 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
21e80 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73   is used when [s
21e90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
21ea0 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53   preparing].** S
21eb0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
21ec0 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  om an untrusted 
21ed0 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72  source, to ensur
21ee0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  e that the SQL s
21ef0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20  tatements.** do 
21f00 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
21f10 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20  s data they are 
21f20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
21f30 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
21f40 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74   do not.** try t
21f50 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  o execute malici
21f60 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
21f70 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
21f80 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
21f90 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
21fa0 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
21fb0 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
21fc0 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
21fd0 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
21fe0 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
21ff0 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
22000 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
22010 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
22020 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
22030 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
22040 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
22050 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
22060 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
22070 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
22080 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
22090 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
220a0 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
220b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
220c0 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
220d0 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
220e0 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
220f0 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
22100 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
22110 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
22120 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
22130 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
22140 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
22150 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
22160 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
22170 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
22180 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
22190 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
221a0 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
221b0 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
221c0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
221d0 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
221e0 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
221f0 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
22200 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67  ** ^(Only a sing
22210 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
22220 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
22230 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
22240 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
22250 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
22260 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
22270 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
22280 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
22290 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69  ous call.)^  ^Di
222a0 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
222b0 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
222c0 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
222d0 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
222e0 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
222f0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
22300 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
22310 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
22320 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
22330 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
22340 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
22350 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
22360 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75  t invoked the au
22370 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
22380 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
22390 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
223a0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
223b0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
223c0 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
223d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
223e0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
223f0 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
22400 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
22410 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  aph..**.** ^When
22420 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22430 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20  e_v2()] is used 
22440 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61  to prepare a sta
22450 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73  tement, the.** s
22460 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62  tatement might b
22470 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75  e re-prepared du
22480 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ring [sqlite3_st
22490 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a  ep()] due to a .
224a0 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  ** schema change
224b0 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70  .  Hence, the ap
224c0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
224d0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
224e0 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68  .** correct auth
224f0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
22500 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65  remains in place
22510 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c   during the [sql
22520 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
22530 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  .** ^Note that t
22540 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
22550 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
22560 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
22570 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22580 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
22590 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
225a0 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
225b0 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
225c0 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
225d0 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
225e0 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73  _step()], unless
225f0 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e  .** as stated in
22600 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
22610 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33  ragraph, sqlite3
22620 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a  _step() invokes.
22630 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
22640 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65  re_v2() to repre
22650 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
22660 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20   after a schema 
22670 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73  change..*/.int s
22680 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
22690 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
226a0 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
226b0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
226c0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
226d0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
226e0 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
226f0 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
22700 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
22710 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
22720 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  eturn Codes.**.*
22730 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
22740 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
22750 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
22760 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
22770 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
22780 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
22790 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
227a0 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
227b0 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
227c0 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
227d0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
227e0 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
227f0 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
22800 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
22810 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
22820 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
22830 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
22840 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
22850 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
22860 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  t SQLITE_IGNORE 
22870 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20  is also used as 
22880 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f  a [conflict reso
22890 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20  lution mode].** 
228a0 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68  returned from th
228b0 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e [sqlite3_vtab_
228c0 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69  on_conflict()] i
228d0 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65  nterface..*/.#de
228e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
228f0 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
22900 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
22910 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
22920 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22930 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
22940 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
22950 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
22960 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
22970 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
22980 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
22990 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
229a0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
229b0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
229c0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
229d0 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
229e0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
229f0 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
22a00 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e  uthorize certain
22a10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
22a20 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
22a30 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
22a40 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
22a50 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
22a60 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
22a70 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
22a80 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
22a90 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
22aa0 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
22ab0 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
22ac0 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
22ad0 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
22ae0 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
22af0 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
22b00 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
22b10 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
22b20 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
22b30 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
22b40 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
22b50 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
22b60 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
22b70 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
22b80 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
22b90 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
22ba0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
22bb0 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
22bc0 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
22bd0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
22be0 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74  meter.  ^(The 5t
22bf0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
22c00 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
22c10 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
22c20 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
22c30 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
22c40 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
22c50 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e  if applicable.)^
22c60 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d    ^The 6th param
22c70 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
22c80 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
22c90 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
22ca0 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
22cb0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
22cc0 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
22cd0 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
22ce0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
22cf0 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
22d00 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
22d10 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
22d20 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
22d30 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
22d40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22d50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22d60 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
22d70 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
22d80 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
22d90 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
22da0 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
22db0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
22dc0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
22dd0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22de0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
22df0 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
22e00 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
22e10 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22e20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22e30 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
22e40 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
22e50 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
22e60 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
22e70 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22e80 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
22e90 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
22ea0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22eb0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22ec0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22ed0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
22ee0 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
22ef0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
22f00 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22f10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22f20 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
22f30 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
22f40 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
22f50 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22f60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22f70 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
22f80 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
22f90 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
22fa0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22fb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22fc0 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
22fd0 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
22fe0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
22ff0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
23000 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
23010 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
23020 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
23030 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
23040 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
23050 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
23060 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
23070 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
23080 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
23090 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
230a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
230b0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
230c0 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
230d0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
230e0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
230f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
23100 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
23110 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
23120 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
23130 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
23140 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
23150 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
23160 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
23170 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
23180 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
23190 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
231a0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
231b0 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
231c0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
231d0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
231e0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
231f0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
23200 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
23210 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
23220 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
23230 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
23240 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
23250 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
23260 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
23270 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23280 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
23290 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
232a0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
232b0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
232c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
232d0 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
232e0 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
232f0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
23300 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
23310 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23320 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
23330 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
23340 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
23350 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
23360 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
23370 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
23380 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
23390 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
233a0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
233b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
233c0 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
233d0 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
233e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
233f0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
23400 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23410 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
23420 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
23430 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
23440 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
23450 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23460 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
23470 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
23480 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
23490 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
234a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
234b0 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
234c0 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
234d0 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
234e0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
234f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
23500 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
23510 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
23520 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
23530 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
23540 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
23550 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
23560 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
23570 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
23580 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
23590 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
235a0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
235b0 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
235c0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
235d0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
235e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
235f0 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
23600 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
23610 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
23620 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
23630 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
23640 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
23650 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
23660 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
23670 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
23680 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
23690 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
236a0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
236b0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
236c0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
236d0 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
236e0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
236f0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
23700 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
23710 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
23720 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
23730 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
23740 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
23750 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
23760 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
23770 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
23780 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
23790 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
237a0 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
237b0 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20  LITE_RECURSIVE  
237c0 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f            33   /
237d0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
237e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
237f0 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    */../*.** CAPI
23800 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
23810 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
23820 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
23830 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
23840 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
23850 65 20 64 65 70 72 65 63 61 74 65 64 2e 20 55 73  e deprecated. Us
23860 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  e the [sqlite3_t
23870 72 61 63 65 5f 76 32 28 29 5d 20 69 6e 74 65 72  race_v2()] inter
23880 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20  face.** instead 
23890 6f 66 20 74 68 65 20 72 6f 75 74 69 6e 65 73 20  of the routines 
238a0 64 65 73 63 72 69 62 65 64 20 68 65 72 65 2e 0a  described here..
238b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
238c0 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
238d0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
238e0 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
238f0 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
23900 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
23910 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
23920 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
23930 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
23940 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
23950 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
23960 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
23970 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
23980 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
23990 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
239a0 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
239b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
239c0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
239d0 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
239e0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
239f0 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  th a UTF-8 rende
23a00 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53  ring of the.** S
23a10 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
23a20 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  t as the stateme
23a30 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
23a40 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28  executing..** ^(
23a50 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74  Additional sqlit
23a60 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
23a70 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72  acks might occur
23a80 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
23a90 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
23aa0 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
23ab0 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
23ac0 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
23ad0 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
23ae0 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
23af0 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
23b00 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ger.)^.**.** The
23b10 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53   [SQLITE_TRACE_S
23b20 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69  IZE_LIMIT] compi
23b30 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63  le-time option c
23b40 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69  an be used to li
23b50 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74  mit.** the lengt
23b60 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61  h of [bound para
23b70 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e  meter] expansion
23b80 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f   in the output o
23b90 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  f sqlite3_trace(
23ba0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  )..**.** ^The ca
23bb0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
23bc0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
23bd0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
23be0 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
23bf0 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
23c00 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e  ent finishes.  ^
23c10 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
23c20 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
23c30 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
23c40 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
23c50 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
23c60 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
23c70 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
23c80 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
23c90 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65  ok to run.  ^The
23ca0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
23cb0 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20  k.** time is in 
23cc0 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63  units of nanosec
23cd0 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68  onds, however th
23ce0 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
23cf0 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f  entation.** is o
23d00 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d  nly capable of m
23d10 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c  illisecond resol
23d20 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78  ution so the six
23d30 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61   least significa
23d40 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20  nt.** digits in 
23d50 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61  the time are mea
23d60 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72  ningless.  Futur
23d70 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
23d80 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72  Lite.** might pr
23d90 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65  ovide greater re
23da0 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20  solution on the 
23db0 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63  profiler callbac
23dc0 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  k.  The.** sqlit
23dd0 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e  e3_profile() fun
23de0 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65  ction is conside
23df0 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  red experimental
23e00 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65   and is.** subje
23e10 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20  ct to change in 
23e20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
23e30 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51  of SQLite..*/.SQ
23e40 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
23e50 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
23e60 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ace(sqlite3*,.  
23e70 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
23e80 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
23e90 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
23ea0 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
23eb0 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
23ec0 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
23ed0 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
23ee0 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
23ef0 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
23f00 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
23f10 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
23f20 54 72 61 63 65 20 45 76 65 6e 74 20 43 6f 64 65  Trace Event Code
23f30 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  s.** KEYWORDS: S
23f40 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a 2a 0a 2a  QLITE_TRACE.**.*
23f50 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
23f60 73 20 69 64 65 6e 74 69 66 79 20 63 6c 61 73 73  s identify class
23f70 65 73 20 6f 66 20 65 76 65 6e 74 73 20 74 68 61  es of events tha
23f80 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69 74 6f 72  t can be monitor
23f90 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20  ed.** using the 
23fa0 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
23fb0 32 28 29 5d 20 74 72 61 63 69 6e 67 20 6c 6f 67  2()] tracing log
23fc0 69 63 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  ic.  The third a
23fd0 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73  rgument.** to [s
23fe0 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
23ff0 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65 64 20 63  )] is an OR-ed c
24000 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e  ombination of on
24010 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20  e or more of.** 
24020 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f  the following co
24030 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68 65 20 66  nstants.  ^The f
24040 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
24050 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62   the trace callb
24060 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f 66  ack.** is one of
24070 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
24080 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  onstants..**.** 
24090 4e 65 77 20 74 72 61 63 69 6e 67 20 63 6f 6e 73  New tracing cons
240a0 74 61 6e 74 73 20 6d 61 79 20 62 65 20 61 64 64  tants may be add
240b0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
240c0 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  eases..**.** ^A 
240d0 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 68  trace callback h
240e0 61 73 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74  as four argument
240f0 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c 43  s: xCallback(T,C
24100 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54  ,P,X)..** ^The T
24110 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
24120 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   of the integer 
24130 74 79 70 65 20 63 6f 64 65 73 20 61 62 6f 76 65  type codes above
24140 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75  ..** ^The C argu
24150 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f  ment is a copy o
24160 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f  f the context po
24170 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 20  inter passed in 
24180 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68  as the.** fourth
24190 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
241a0 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
241b0 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20  ]..** The P and 
241c0 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20  X arguments are 
241d0 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d  pointers whose m
241e0 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f  eanings depend o
241f0 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  n T..**.** <dl>.
24200 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43  ** [[SQLITE_TRAC
24210 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c  E_STMT]] <dt>SQL
24220 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c 2f  ITE_TRACE_STMT</
24230 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53  dt>.** <dd>^An S
24240 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54  QLITE_TRACE_STMT
24250 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
24260 6f 6b 65 64 20 77 68 65 6e 20 61 20 70 72 65 70  oked when a prep
24270 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
24280 2a 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 72  * first begins r
24290 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73 69  unning and possi
242a0 62 6c 79 20 61 74 20 6f 74 68 65 72 20 74 69 6d  bly at other tim
242b0 65 73 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a  es during the.**
242c0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
242d0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
242e0 6d 65 6e 74 2c 20 73 75 63 68 20 61 73 20 61 74  ment, such as at
242f0 20 74 68 65 20 73 74 61 72 74 20 6f 66 20 65 61   the start of ea
24300 63 68 0a 2a 2a 20 74 72 69 67 67 65 72 20 73 75  ch.** trigger su
24310 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20 50  bprogram. ^The P
24320 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
24330 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
24340 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24350 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61 72  ment]. ^The X ar
24360 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
24370 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
24380 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
24390 75 6e 65 78 70 61 6e 64 65 64 20 53 51 4c 20 74  unexpanded SQL t
243a0 65 78 74 20 6f 66 20 74 68 65 20 70 72 65 70 61  ext of the prepa
243b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  red statement or
243c0 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20   an SQL comment 
243d0 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74  .** that indicat
243e0 65 73 20 74 68 65 20 69 6e 76 6f 63 61 74 69 6f  es the invocatio
243f0 6e 20 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20  n of a trigger. 
24400 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 63   ^The callback c
24410 61 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74 68  an compute.** th
24420 65 20 73 61 6d 65 20 74 65 78 74 20 74 68 61 74  e same text that
24430 20 77 6f 75 6c 64 20 68 61 76 65 20 62 65 65 6e   would have been
24440 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
24450 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
24460 5f 74 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e 74  _trace()].** int
24470 65 72 66 61 63 65 20 62 79 20 75 73 69 6e 67 20  erface by using 
24480 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 77  the X argument w
24490 68 65 6e 20 58 20 62 65 67 69 6e 73 20 77 69 74  hen X begins wit
244a0 68 20 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f 6b  h "--" and invok
244b0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
244c0 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 5d  expanded_sql(P)]
244d0 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
244e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  * [[SQLITE_TRACE
244f0 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53  _PROFILE]] <dt>S
24500 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46  QLITE_TRACE_PROF
24510 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ILE</dt>.** <dd>
24520 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ^An SQLITE_TRACE
24530 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63  _PROFILE callbac
24540 6b 20 70 72 6f 76 69 64 65 73 20 61 70 70 72 6f  k provides appro
24550 78 69 6d 61 74 65 6c 79 20 74 68 65 20 73 61 6d  ximately the sam
24560 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
24570 20 61 73 20 69 73 20 70 72 6f 76 69 64 65 64 20   as is provided 
24580 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
24590 70 72 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62  profile()] callb
245a0 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61  ack..** ^The P a
245b0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
245c0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65  nter to the [pre
245d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
245e0 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72   and the.** X ar
245f0 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f  gument points to
24600 20 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65   a 64-bit intege
24610 72 20 77 68 69 63 68 20 69 73 20 74 68 65 20 65  r which is the e
24620 73 74 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74  stimated of.** t
24630 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e  he number of nan
24640 6f 73 65 63 6f 6e 64 20 74 68 61 74 20 74 68 65  osecond that the
24650 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
24660 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e  ent took to run.
24670 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  .** ^The SQLITE_
24680 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61  TRACE_PROFILE ca
24690 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
246a0 64 20 77 68 65 6e 20 74 68 65 20 73 74 61 74 65  d when the state
246b0 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a  ment finishes..*
246c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  *.** [[SQLITE_TR
246d0 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51  ACE_ROW]] <dt>SQ
246e0 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f  LITE_TRACE_ROW</
246f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53  dt>.** <dd>^An S
24700 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20  QLITE_TRACE_ROW 
24710 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
24720 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 70  ked whenever a p
24730 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
24740 6d 65 6e 74 20 67 65 6e 65 72 61 74 65 73 20 61  ment generates a
24750 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72   single row of r
24760 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65  esult.  .** ^The
24770 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   P argument is a
24780 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
24790 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
247a0 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20  ent] and the.** 
247b0 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e  X argument is un
247c0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  used..**.** [[SQ
247d0 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45  LITE_TRACE_CLOSE
247e0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52  ]] <dt>SQLITE_TR
247f0 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a  ACE_CLOSE</dt>.*
24800 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45  * <dd>^An SQLITE
24810 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c  _TRACE_CLOSE cal
24820 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
24830 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
24840 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  .** connection c
24850 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50  loses..** ^The P
24860 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
24870 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64  ointer to the [d
24880 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24890 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  on] object.** an
248a0 64 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74  d the X argument
248b0 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c   is unused..** <
248c0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
248d0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
248e0 54 20 20 20 20 20 20 20 30 78 30 31 0a 23 64 65  T       0x01.#de
248f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43  fine SQLITE_TRAC
24900 45 5f 50 52 4f 46 49 4c 45 20 20 20 20 30 78 30  E_PROFILE    0x0
24910 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
24920 5f 54 52 41 43 45 5f 52 4f 57 20 20 20 20 20 20  _TRACE_ROW      
24930 20 20 30 78 30 34 0a 23 64 65 66 69 6e 65 20 53    0x04.#define S
24940 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
24950 45 20 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a  E      0x08../*.
24960 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
24970 20 54 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d   Trace Hook.** M
24980 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
24990 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
249a0 33 5f 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58  3_trace_v2(D,M,X
249b0 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,P) interface re
249c0 67 69 73 74 65 72 73 20 61 20 74 72 61 63 65 20  gisters a trace 
249d0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
249e0 74 69 6f 6e 20 58 20 61 67 61 69 6e 73 74 20 5b  tion X against [
249f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24a00 69 6f 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70 72  ion] D, using pr
24a10 6f 70 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a  operty mask M.**
24a20 20 61 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f 69   and context poi
24a30 6e 74 65 72 20 50 2e 20 20 5e 49 66 20 74 68 65  nter P.  ^If the
24a40 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a   X callback is.*
24a50 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68 65  * NULL or if the
24a60 20 4d 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c   M mask is zero,
24a70 20 74 68 65 6e 20 74 72 61 63 69 6e 67 20 69 73   then tracing is
24a80 20 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65 0a   disabled.  The.
24a90 2a 2a 20 4d 20 61 72 67 75 6d 65 6e 74 20 73 68  ** M argument sh
24aa0 6f 75 6c 64 20 62 65 20 74 68 65 20 62 69 74 77  ould be the bitw
24ab0 69 73 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e  ise OR-ed combin
24ac0 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f  ation of.** zero
24ad0 20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45   or more [SQLITE
24ae0 5f 54 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e 74  _TRACE] constant
24af0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 63  s..**.** ^Each c
24b00 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 73 71  all to either sq
24b10 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72  lite3_trace() or
24b20 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
24b30 32 28 29 20 6f 76 65 72 72 69 64 65 73 20 0a 2a  2() overrides .*
24b40 2a 20 28 63 61 6e 63 65 6c 73 29 20 61 6e 79 20  * (cancels) any 
24b50 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73  prior calls to s
24b60 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f  qlite3_trace() o
24b70 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f  r sqlite3_trace_
24b80 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  v2()..**.** ^The
24b90 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69   X callback is i
24ba0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
24bb0 61 6e 79 20 6f 66 20 74 68 65 20 65 76 65 6e 74  any of the event
24bc0 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  s identified by 
24bd0 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75 72  .** mask M occur
24be0 2e 20 20 5e 54 68 65 20 69 6e 74 65 67 65 72 20  .  ^The integer 
24bf0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
24c00 6d 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  m the callback i
24c10 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 69  s currently.** i
24c20 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67 68 20 74  gnored, though t
24c30 68 69 73 20 6d 61 79 20 63 68 61 6e 67 65 20 69  his may change i
24c40 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
24c50 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s.  Callback.** 
24c60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
24c70 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a 65  should return ze
24c80 72 6f 20 74 6f 20 65 6e 73 75 72 65 20 66 75 74  ro to ensure fut
24c90 75 72 65 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ure compatibilit
24ca0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63  y..**.** ^A trac
24cb0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
24cc0 76 6f 6b 65 64 20 77 69 74 68 20 66 6f 75 72 20  voked with four 
24cd0 61 72 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c 62  arguments: callb
24ce0 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a  ack(T,C,P,X)..**
24cf0 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74   ^The T argument
24d00 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
24d10 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a 2a  SQLITE_TRACE].**
24d20 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69 6e   constants to in
24d30 64 69 63 61 74 65 20 77 68 79 20 74 68 65 20 63  dicate why the c
24d40 61 6c 6c 62 61 63 6b 20 77 61 73 20 69 6e 76 6f  allback was invo
24d50 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61  ked..** ^The C a
24d60 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70  rgument is a cop
24d70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74  y of the context
24d80 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 65   pointer..** The
24d90 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e   P and X argumen
24da0 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20  ts are pointers 
24db0 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64  whose meanings d
24dc0 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a  epend on T..**.*
24dd0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72  * The sqlite3_tr
24de0 61 63 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61  ace_v2() interfa
24df0 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  ce is intended t
24e00 6f 20 72 65 70 6c 61 63 65 20 74 68 65 20 6c 65  o replace the le
24e10 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
24e20 65 73 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  es [sqlite3_trac
24e30 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
24e40 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62 6f  3_profile()], bo
24e50 74 68 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20 61  th of which.** a
24e60 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 0a 2a  re deprecated..*
24e70 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72  /.int sqlite3_tr
24e80 61 63 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ace_v2(.  sqlite
24e90 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75  3*,.  unsigned u
24ea0 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61  Mask,.  int(*xCa
24eb0 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64  llback)(unsigned
24ec0 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69  ,void*,void*,voi
24ed0 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74  d*),.  void *pCt
24ee0 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x.);../*.** CAPI
24ef0 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
24f00 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
24f10 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
24f20 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
24f30 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
24f40 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69  ndler(D,N,X,P) i
24f50 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
24f60 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
24f70 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65  function X to be
24f80 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
24f90 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
24fa0 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
24fb0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  to.** [sqlite3_e
24fc0 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
24fd0 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71  _step()] and [sq
24fe0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
24ff0 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61  )] for.** databa
25000 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
25010 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
25020 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
25030 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
25040 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
25050 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
25060 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  uery..**.** ^The
25070 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
25080 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
25090 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
250a0 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  eter to the .** 
250b0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
250c0 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  n X.  ^The param
250d0 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70  eter N is the ap
250e0 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72  proximate number
250f0 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   of .** [virtual
25100 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63   machine instruc
25110 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20  tions] that are 
25120 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65  evaluated betwee
25130 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20  n successive.** 
25140 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
25150 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20  he callback X.  
25160 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68  ^If N is less th
25170 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20  an one then the 
25180 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64  progress.** hand
25190 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ler is disabled.
251a0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73  .**.** ^Only a s
251b0 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68  ingle progress h
251c0 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65  andler may be de
251d0 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d  fined at one tim
251e0 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61  e per.** [databa
251f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20  se connection]; 
25200 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72  setting a new pr
25210 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
25220 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c  ancels the.** ol
25230 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67  d one.  ^Setting
25240 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20   parameter X to 
25250 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68  NULL disables th
25260 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
25270 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67  er..** ^The prog
25280 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20  ress handler is 
25290 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79  also disabled by
252a0 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20   setting N to a 
252b0 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68  value less.** th
252c0 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  an 1..**.** ^If 
252d0 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
252e0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
252f0 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
25300 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
25310 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
25320 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
25330 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
25340 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
25350 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
25360 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
25370 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
25380 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
25390 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
253a0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
253b0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
253c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
253d0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
253e0 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
253f0 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
25400 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
25410 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
25420 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
25430 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
25440 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
25450 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
25460 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
25470 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
25480 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
25490 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
254a0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
254b0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
254c0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
254d0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
254e0 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
254f0 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
25500 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e  onnection.** CON
25510 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
25520 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  3.**.** ^These r
25530 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20  outines open an 
25540 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
25550 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65  file as specifie
25560 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c  d by the .** fil
25570 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20  ename argument. 
25580 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72  ^The filename ar
25590 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
255a0 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66  reted as UTF-8 f
255b0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
255c0 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
255d0 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61  _open_v2() and a
255e0 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
255f0 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f  native byte.** o
25600 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
25610 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b  _open16(). ^(A [
25620 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25630 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75  ion] handle is u
25640 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e  sually.** return
25650 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65  ed in *ppDb, eve
25660 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  n if an error oc
25670 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  curs.  The only 
25680 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61  exception is tha
25690 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69  t.** if SQLite i
256a0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
256b0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68  cate memory to h
256c0 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  old the [sqlite3
256d0 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e  ] object,.** a N
256e0 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74  ULL will be writ
256f0 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69  ten into *ppDb i
25700 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e  nstead of a poin
25710 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
25720 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29  te3].** object.)
25730 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62  ^ ^(If the datab
25740 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61  ase is opened (a
25750 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73  nd/or created) s
25760 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65  uccessfully, the
25770 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  n.** [SQLITE_OK]
25780 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
25790 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
257a0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
257b0 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20  rned.)^ ^The.** 
257c0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
257d0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  )] or [sqlite3_e
257e0 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69  rrmsg16()] routi
257f0 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
25800 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20  to obtain.** an 
25810 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65  English language
25820 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20   description of 
25830 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77  the error follow
25840 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66  ing a failure of
25850 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73   any.** of the s
25860 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f  qlite3_open() ro
25870 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  utines..**.** ^T
25880 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
25890 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ing will be UTF-
258a0 38 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 20  8 for databases 
258b0 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
258c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
258d0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
258e0 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61  v2().  ^The defa
258f0 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ult encoding for
25900 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72   databases.** cr
25910 65 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69  eated using sqli
25920 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c  te3_open16() wil
25930 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74  l be UTF-16 in t
25940 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
25950 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  rder..**.** Whet
25960 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
25970 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
25980 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
25990 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
259a0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
259b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
259c0 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75  ion] handle shou
259d0 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ld be released b
259e0 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20  y.** passing it 
259f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
25a00 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20  e()] when it is 
25a10 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
25a20 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
25a30 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
25a40 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
25a50 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65  like sqlite3_ope
25a60 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
25a70 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77  at it accepts tw
25a80 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
25a90 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
25aa0 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a  tional control.*
25ab0 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64  * over the new d
25ac0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25ad0 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73  on.  ^(The flags
25ae0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
25af0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
25b00 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20  () can take one 
25b10 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
25b20 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73  ing three values
25b30 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  , optionally com
25b40 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a  bined with the .
25b50 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
25b60 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  NOMUTEX], [SQLIT
25b70 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
25b80 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
25b90 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a  SHAREDCACHE],.**
25ba0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
25bb0 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64  IVATECACHE], and
25bc0 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  /or [SQLITE_OPEN
25bd0 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a  _URI] flags:)^.*
25be0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
25bf0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
25c00 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a  READONLY]</dt>.*
25c10 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
25c20 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  se is opened in 
25c30 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20  read-only mode. 
25c40 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
25c50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72   does not.** alr
25c60 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65  eady exist, an e
25c70 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
25c80 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
25c90 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
25ca0 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
25cb0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
25cc0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
25cd0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
25ce0 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
25cf0 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
25d00 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
25d10 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
25d20 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
25d30 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
25d40 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
25d50 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
25d60 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
25d70 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
25d80 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
25d90 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
25da0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
25db0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
25dc0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
25dd0 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  EATE]</dt>.** <d
25de0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
25df0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
25e00 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
25e10 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64  , and is created
25e20 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e   if.** it does n
25e30 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
25e40 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65  . This is the be
25e50 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
25e60 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a  lways used for.*
25e70 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
25e80 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
25e90 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  n16().</dd>)^.**
25ea0 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </dl>.**.** If 
25eb0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
25ec0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
25ed0 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e  n_v2() is not on
25ee0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62  e of the.** comb
25ef0 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
25f00 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  bove optionally 
25f10 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74  combined with ot
25f20 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  her.** [SQLITE_O
25f30 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53  PEN_READONLY | S
25f40 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74  QLITE_OPEN_* bit
25f50 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  s].** then the b
25f60 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
25f70 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ined..**.** ^If 
25f80 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
25f90 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  _NOMUTEX] flag i
25fa0 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20  s set, then the 
25fb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25fc0 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20  ion.** opens in 
25fd0 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  the multi-thread
25fe0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
25ff0 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  ] as long as the
26000 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a   single-thread.*
26010 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62  * mode has not b
26020 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69  een set at compi
26030 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
26040 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a  -time.  ^If the.
26050 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
26060 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
26070 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
26080 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
26090 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
260a0 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
260b0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
260c0 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
260d0 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
260e0 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
260f0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
26100 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
26110 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
26120 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
26130 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
26140 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
26150 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c  tion to be.** el
26160 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73  igible to use [s
26170 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
26180 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ], regardless of
26190 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
261a0 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
261b0 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  is enabled using
261c0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
261d0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
261e0 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49  .  ^The.** [SQLI
261f0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
26200 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
26210 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
26220 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74  onnection to not
26230 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20  .** participate 
26240 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  in [shared cache
26250 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69   mode] even if i
26260 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  t is enabled..**
26270 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
26280 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
26290 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
262a0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
262b0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
262c0 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
262d0 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
262e0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
262f0 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
26300 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
26310 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
26320 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66   use.  ^If the f
26330 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
26340 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
26350 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
26360 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
26370 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
26380 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
26390 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a  e filename is ":
263a0 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
263b0 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
263c0 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  ary in-memory da
263d0 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65  tabase.** is cre
263e0 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
263f0 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20  nection.  ^This 
26400 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
26410 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77  se will vanish w
26420 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  hen.** the datab
26430 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
26440 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72  s closed.  Futur
26450 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
26460 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61  Lite might.** ma
26470 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
26480 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
26490 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69  enames that begi
264a0 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63  n with the ":" c
264b0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20  haracter..** It 
264c0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
264d0 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62  hat when a datab
264e0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74  ase filename act
264f0 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e  ually does begin
26500 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63   with.** a ":" c
26510 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f  haracter you sho
26520 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66  uld prefix the f
26530 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70  ilename with a p
26540 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a  athname such as.
26550 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64  ** "./" to avoid
26560 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a   ambiguity..**.*
26570 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
26580 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
26590 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
265a0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
265b0 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
265c0 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
265d0 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69  ated.  ^This pri
265e0 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
265f0 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
26600 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
26610 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
26620 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26630 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
26640 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
26650 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70  es in sqlite3_op
26660 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46  en()]] <h3>URI F
26670 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a  ilenames</h3>.**
26680 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c  .** ^If [URI fil
26690 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74  ename] interpret
266a0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
266b0 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61  , and the filena
266c0 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62  me argument.** b
266d0 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65  egins with "file
266e0 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c  :", then the fil
266f0 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72  ename is interpr
26700 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e  eted as a URI. ^
26710 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  URI.** filename 
26720 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
26730 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
26740 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
26750 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65  I] flag is.** se
26760 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 61  t in the third a
26770 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
26780 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72  e3_open_v2(), or
26790 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65   if it has.** be
267a0 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61  en enabled globa
267b0 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53  lly using the [S
267c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
267d0 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68  ] option with th
267e0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
267f0 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f  nfig()] method o
26800 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  r by the [SQLITE
26810 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c  _USE_URI] compil
26820 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
26830 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69  * URI filename i
26840 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
26850 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62   turned off.** b
26860 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66  y default, but f
26870 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
26880 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65  f SQLite might e
26890 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61  nable URI filena
268a0 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61  me.** interpreta
268b0 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  tion by default.
268c0 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65    See "[URI file
268d0 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69  names]" for addi
268e0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
268f0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49  ation..**.** URI
26900 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70   filenames are p
26910 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20  arsed according 
26920 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66  to RFC 3986. ^If
26930 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e   the URI contain
26940 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74  s an.** authorit
26950 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20  y, then it must 
26960 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70  be either an emp
26970 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65  ty string or the
26980 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63   string .** "loc
26990 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65  alhost". ^If the
269a0 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f   authority is no
269b0 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  t an empty strin
269c0 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22  g or "localhost"
269d0 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69  , an .** error i
269e0 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68  s returned to th
269f0 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66  e caller. ^The f
26a00 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e  ragment componen
26a10 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a  t of a URI, if .
26a20 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69  ** present, is i
26a30 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  gnored..**.** ^S
26a40 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70  QLite uses the p
26a50 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ath component of
26a60 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20   the URI as the 
26a70 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b  name of the disk
26a80 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63   file.** which c
26a90 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61  ontains the data
26aa0 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61  base. ^If the pa
26ab0 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  th begins with a
26ac0 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20   '/' character, 
26ad0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69  .** then it is i
26ae0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e  nterpreted as an
26af0 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20   absolute path. 
26b00 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65  ^If the path doe
26b10 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20  s not begin .** 
26b20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e  with a '/' (mean
26b30 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74  ing that the aut
26b40 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69  hority section i
26b50 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
26b60 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20  he URI).** then 
26b70 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65  the path is inte
26b80 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c  rpreted as a rel
26b90 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20  ative path. .** 
26ba0 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68  ^(On windows, th
26bb0 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e  e first componen
26bc0 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65  t of an absolute
26bd0 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64   path .** is a d
26be0 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69  rive specificati
26bf0 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29  on (e.g. "C:").)
26c00 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55  ^.**.** [[core U
26c10 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  RI query paramet
26c20 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65  ers]].** The que
26c30 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
26c40 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69  a URI may contai
26c50 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
26c60 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  t are interprete
26c70 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53  d.** either by S
26c80 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72  QLite itself, or
26c90 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73   by a [VFS | cus
26ca0 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  tom VFS implemen
26cb0 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69  tation]..** SQLi
26cc0 74 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74  te and its built
26cd0 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65  -in [VFSes] inte
26ce0 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c  rpret the.** fol
26cf0 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72  lowing query par
26d00 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ameters:.**.** <
26d10 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  ul>.**   <li> <b
26d20 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22  >vfs</b>: ^The "
26d30 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d  vfs" parameter m
26d40 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70  ay be used to sp
26d50 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f  ecify the name o
26d60 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f  f.**     a VFS o
26d70 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69  bject that provi
26d80 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  des the operatin
26d90 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
26da0 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a  ce that should.*
26db0 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f  *     be used to
26dc0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
26dd0 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73  base file on dis
26de0 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69  k. ^If this opti
26df0 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20  on is set to.** 
26e00 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72      an empty str
26e10 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20  ing the default 
26e20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73  VFS object is us
26e30 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20  ed. ^Specifying 
26e40 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20  an unknown.**   
26e50 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f    VFS is an erro
26e60 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f  r. ^If sqlite3_o
26e70 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
26e80 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74   and the vfs opt
26e90 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72  ion is.**     pr
26ea0 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20  esent, then the 
26eb0 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79  VFS specified by
26ec0 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65   the option take
26ed0 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65  s precedence ove
26ee0 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c  r.**     the val
26ef0 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
26f00 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
26f10 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
26f20 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
26f30 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e  <li> <b>mode</b>
26f40 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72  : ^(The mode par
26f50 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
26f60 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22  t to either "ro"
26f70 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22  , "rw",.**     "
26f80 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79  rwc", or "memory
26f90 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f  ". Attempting to
26fa0 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f   set it to any o
26fb0 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a  ther value is.**
26fc0 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e       an error)^.
26fd0 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f   .**     ^If "ro
26fe0 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20  " is specified, 
26ff0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
27000 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
27010 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20  read-only .**   
27020 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61    access, just a
27030 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  s if the [SQLITE
27040 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20  _OPEN_READONLY] 
27050 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65  flag had been se
27060 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20  t in the .**    
27070 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
27080 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
27090 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f  v2(). ^If the mo
270a0 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  de option is set
270b0 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22   to .**     "rw"
270c0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
270d0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
270e0 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75  r read-write (bu
270f0 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a  t not create) .*
27100 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73  *     access, as
27110 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   if SQLITE_OPEN_
27120 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e  READWRITE (but n
27130 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ot SQLITE_OPEN_C
27140 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20  REATE) had .**  
27150 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61     been set. ^Va
27160 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75  lue "rwc" is equ
27170 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
27180 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20  ng both .**     
27190 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
271a0 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45  WRITE and SQLITE
271b0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e  _OPEN_CREATE.  ^
271c0 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
271d0 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74  on is.**     set
271e0 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65   to "memory" the
271f0 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d  n a pure [in-mem
27200 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68  ory database] th
27210 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a  at never reads.*
27220 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20  *     or writes 
27230 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65  from disk is use
27240 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72  d. ^It is an err
27250 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20  or to specify a 
27260 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20  value for.**    
27270 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65   the mode parame
27280 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73  ter that is less
27290 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61   restrictive tha
272a0 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64  n that specified
272b0 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66   by.**     the f
272c0 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74  lags passed in t
272d0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
272e0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
272f0 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
27300 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f   <li> <b>cache</
27310 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70  b>: ^The cache p
27320 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
27330 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73  set to either "s
27340 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20  hared" or.**    
27350 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74   "private". ^Set
27360 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72  ting it to "shar
27370 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ed" is equivalen
27380 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
27390 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
273a0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
273b0 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73  bit in the flags
273c0 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
273d0 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74   to.**     sqlit
273e0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53  e3_open_v2(). ^S
273f0 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65  etting the cache
27400 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70   parameter to "p
27410 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20  rivate" is .**  
27420 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f     equivalent to
27430 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c   setting the SQL
27440 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
27450 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20  CACHE bit..**   
27460 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70    ^If sqlite3_op
27470 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
27480 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20  and the "cache" 
27490 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65  parameter is pre
274a0 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61  sent in.**     a
274b0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69   URI filename, i
274c0 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64  ts value overrid
274d0 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20  es any behavior 
274e0 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74  requested by set
274f0 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49  ting.**     SQLI
27500 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
27510 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f  ACHE or SQLITE_O
27520 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
27530 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  flag..**.**  <li
27540 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e  > <b>psow</b>: ^
27550 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74  The psow paramet
27560 65 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65  er indicates whe
27570 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a  ther or not the.
27580 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66  **     [powersaf
27590 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f  e overwrite] pro
275a0 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f  perty does or do
275b0 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20  es not apply to 
275c0 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61  the.**     stora
275d0 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63  ge media on whic
275e0 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  h the database f
275f0 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a  ile resides..**.
27600 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f  **  <li> <b>nolo
27610 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c  ck</b>: ^The nol
27620 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ock parameter is
27630 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
27640 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
27650 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64    which if set d
27660 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63  isables file loc
27670 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b  king in rollback
27680 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20   journal modes. 
27690 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20   This.**     is 
276a0 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73  useful for acces
276b0 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20  sing a database 
276c0 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20  on a filesystem 
276d0 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  that does not.**
276e0 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63       support loc
276f0 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20  king.  Caution: 
27700 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   Database corrup
27710 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c  tion might resul
27720 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20  t if two.**     
27730 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65  or more processe
27740 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73  s write to the s
27750 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  ame database and
27760 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73   any one of thos
27770 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73  e.**     process
27780 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31  es uses nolock=1
27790 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
277a0 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20  >immutable</b>: 
277b0 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70  ^The immutable p
277c0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f  arameter is a bo
277d0 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20  olean query.**  
277e0 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61     parameter tha
277f0 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  t indicates that
27800 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
27810 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a  le is stored on.
27820 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79  **     read-only
27830 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69   media.  ^When i
27840 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c  mmutable is set,
27850 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
27860 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20  that the.**     
27870 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61  database file ca
27880 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c  nnot be changed,
27890 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65   even by a proce
278a0 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a  ss with higher.*
278b0 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c  *     privilege,
278c0 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61   and so the data
278d0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72  base is opened r
278e0 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c  ead-only and all
278f0 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20   locking.**     
27900 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63  and change detec
27910 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64  tion is disabled
27920 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74  .  Caution: Sett
27930 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c  ing the immutabl
27940 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74  e.**     propert
27950 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  y on a database 
27960 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69  file that does i
27970 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61  n fact change ca
27980 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20  n result.**     
27990 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65  in incorrect que
279a0 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f  ry results and/o
279b0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  r [SQLITE_CORRUP
279c0 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20  T] errors..**   
279d0 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c    See also: [SQL
279e0 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
279f0 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a  BLE]..**       .
27a00 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
27a10 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
27a20 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20  known parameter 
27a30 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d  in the query com
27a40 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
27a50 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72  is not an.** err
27a60 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  or.  Future vers
27a70 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
27a80 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20  ight understand 
27a90 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79  additional query
27aa0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
27ab0 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72   See "[query par
27ac0 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65  ameters with spe
27ad0 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20  cial meaning to 
27ae0 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20  SQLite]" for.** 
27af0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
27b00 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  mation..**.** [[
27b10 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
27b20 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20  mples]] <h3>URI 
27b30 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
27b40 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61  s</h3>.**.** <ta
27b50 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61  ble border="1" a
27b60 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c  lign=center cell
27b70 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74  padding=5>.** <t
27b80 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e  r><th> URI filen
27b90 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74  ames <th> Result
27ba0 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  s.** <tr><td> fi
27bb0 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  le:data.db <td> 
27bc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
27bd0 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
27be0 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
27bf0 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ent directory..*
27c00 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
27c10 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
27c20 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20  db<br>.**       
27c30 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f     file:///home/
27c40 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
27c50 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
27c60 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f  ile://localhost/
27c70 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
27c80 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20  b <br> <td> .** 
27c90 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
27ca0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
27cb0 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
27cc0 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  .db"..** <tr><td
27cd0 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61  > file://darksta
27ce0 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  r/home/fred/data
27cf0 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
27d00 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
27d10 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f  "darkstar" is no
27d20 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61  t a recognized a
27d30 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72  uthority..** <tr
27d40 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74  ><td style="whit
27d50 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e  e-space:nowrap">
27d60 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
27d70 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e  le:///C:/Documen
27d80 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69  ts%20and%20Setti
27d90 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70  ngs/fred/Desktop
27da0 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20  /data.db.**     
27db0 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c  <td> Windows onl
27dc0 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65  y: Open the file
27dd0 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72   "data.db" on fr
27de0 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20  ed's desktop on 
27df0 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  drive.**        
27e00 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20    C:. Note that 
27e10 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67  the %20 escaping
27e20 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65   in this example
27e30 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79   is not strictly
27e40 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65   .**          ne
27e50 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20  cessary - space 
27e60 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62  characters can b
27e70 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79  e used literally
27e80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
27e90 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a  URI filenames..*
27ea0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
27eb0 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26  data.db?mode=ro&
27ec0 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74  cache=private <t
27ed0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
27ee0 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e  Open file "data.
27ef0 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
27f00 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72  nt directory for
27f10 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73   read-only acces
27f20 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52  s..**          R
27f30 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
27f40 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
27f50 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73  ed-cache mode is
27f60 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20   enabled by.**  
27f70 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c          default,
27f80 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63   use a private c
27f90 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ache..** <tr><td
27fa0 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
27fb0 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e  d/data.db?vfs=un
27fc0 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a  ix-dotfile <td>.
27fd0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
27fe0 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
27ff0 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20  d/data.db". Use 
28000 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
28010 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a  "unix-dotfile".*
28020 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
28030 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69  uses dot-files i
28040 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78  n place of posix
28050 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e   advisory lockin
28060 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  g..** <tr><td> f
28070 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
28080 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a  =readonly <td> .
28090 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
280a0 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22  rror. "readonly"
280b0 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20   is not a valid 
280c0 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22  option for the "
280d0 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e  mode" parameter.
280e0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a  .** </table>.**.
280f0 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69  ** ^URI hexadeci
28100 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
28110 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73  nces (%HH) are s
28120 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20  upported within 
28130 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20  the path and.** 
28140 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
28150 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78   of a URI. A hex
28160 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
28170 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74  sequence consist
28180 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e  s of a.** percen
28190 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66  t sign - "%" - f
281a0 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74  ollowed by exact
281b0 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d  ly two hexadecim
281c0 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70  al digits .** sp
281d0 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65  ecifying an octe
281e0 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65  t value. ^Before
281f0 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65   the path or que
28200 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
28210 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61   a.** URI filena
28220 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  me are interpret
28230 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63  ed, they are enc
28240 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
28250 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78   and all .** hex
28260 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
28270 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63  sequences replac
28280 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62  ed by a single b
28290 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  yte containing t
282a0 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64  he.** correspond
282b0 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68  ing octet. If th
282c0 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72  is process gener
282d0 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20  ates an invalid 
282e0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a  UTF-8 encoding,.
282f0 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ** the results a
28300 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
28310 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
28320 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
28330 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
28340 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
28350 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
28360 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
28370 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
28380 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
28390 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
283a0 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
283b0 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
283c0 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
283d0 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
283e0 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
283f0 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
28400 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
28410 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
28420 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
28430 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
28440 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
28450 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62  n_v2()..**.** <b
28460 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
28470 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c   Runtime users:<
28480 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61  /b>  The tempora
28490 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73  ry directory mus
284a0 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f  t be set.** prio
284b0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c  r to calling sql
284c0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
284d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
284e0 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61  .  Otherwise, va
284f0 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65  rious.** feature
28500 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74  s that require t
28510 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72  he use of tempor
28520 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61  ary files may fa
28530 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  il..**.** See al
28540 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d  so: [sqlite3_tem
28550 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a  p_directory].*/.
28560 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
28570 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
28580 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
28590 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
285a0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
285b0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
285c0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
285d0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
285e0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
285f0 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
28600 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
28610 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
28620 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
28630 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
28640 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
28650 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
28660 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
28670 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
28680 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
28690 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
286a0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
286b0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
286c0 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
286d0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
286e0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
286f0 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
28700 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
28710 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
28720 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
28730 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
28740 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
28750 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
28760 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
28770 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
28780 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
28790 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
287a0 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
287b0 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
287c0 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
287d0 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
287e0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
287f0 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
28800 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
28810 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
28820 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
28830 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
28840 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
28850 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
28860 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
28870 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
28880 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
28890 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
288a0 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
288b0 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
288c0 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
288d0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
288e0 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
288f0 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
28900 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
28910 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
28920 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
28930 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
28940 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
28950 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
28960 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
28970 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
28980 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
28990 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
289a0 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
289b0 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
289c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
289d0 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
289e0 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
289f0 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
28a00 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
28a10 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
28a20 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
28a30 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
28a40 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
28a50 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
28a60 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
28a70 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
28a80 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
28a90 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
28aa0 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
28ab0 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
28ac0 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
28ad0 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
28ae0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
28af0 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
28b00 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
28b10 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
28b20 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
28b30 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
28b40 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
28b50 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
28b60 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
28b70 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
28b80 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
28b90 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
28ba0 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
28bb0 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
28bc0 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
28bd0 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
28be0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
28bf0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
28c00 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
28c10 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
28c20 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
28c30 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
28c40 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
28c50 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
28c60 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
28c70 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
28c80 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
28c90 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
28ca0 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
28cb0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
28cc0 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
28cd0 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
28ce0 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
28cf0 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
28d00 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
28d10 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
28d20 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
28d30 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
28d40 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
28d50 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
28d60 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
28d70 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
28d80 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
28d90 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
28da0 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
28db0 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
28dc0 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
28dd0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
28de0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
28df0 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
28e00 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
28e10 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
28e20 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
28e30 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
28e40 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
28e50 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
28e60 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
28e70 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
28e80 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
28e90 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
28ea0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
28eb0 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
28ec0 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
28ed0 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
28ee0 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
28ef0 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
28f00 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
28f10 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
28f20 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
28f30 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
28f40 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
28f50 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f  desirable..*/.co
28f60 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
28f70 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
28f80 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
28f90 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61  ename, const cha
28fa0 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20  r *zParam);.int 
28fb0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
28fc0 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ean(const char *
28fd0 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61  zFile, const cha
28fe0 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62  r *zParam, int b
28ff0 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65  Default);.sqlite
29000 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
29010 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20  uri_int64(const 
29020 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61  char*, const cha
29030 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
29040 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  4);.../*.** CAPI
29050 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
29060 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
29070 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
29080 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  3.**.** ^If the 
29090 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69  most recent sqli
290a0 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61  te3_* API call a
290b0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a  ssociated with .
290c0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
290d0 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65  nection] D faile
290e0 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  d, then the sqli
290f0 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69  te3_errcode(D) i
29100 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75  nterface.** retu
29110 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
29120 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
29130 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
29140 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74  t code] for that
29150 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a  .** API call..**
29160 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   If the most rec
29170 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73  ent API call was
29180 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20   successful,.** 
29190 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
291a0 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
291b0 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20  e3_errcode() is 
291c0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54  undefined..** ^T
291d0 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
291e0 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a  ded_errcode().**
291f0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
29200 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68  e same except th
29210 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  at it always ret
29220 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78  urns the .** [ex
29230 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
29240 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78  de] even when ex
29250 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
29260 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  des are.** disab
29270 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
29280 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
29290 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72   and sqlite3_err
292a0 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45  msg16() return E
292b0 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a  nglish-language.
292c0 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73  ** text that des
292d0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
292e0 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  , as either UTF-
292f0 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70  8 or UTF-16 resp
29300 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d  ectively..** ^(M
29310 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
29320 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
29330 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
29340 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a  d internally..**
29350 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
29360 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
29370 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72  o worry about fr
29380 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  eeing the result
29390 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
293a0 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d  e error string m
293b0 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74  ight be overwrit
293c0 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ten or deallocat
293d0 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75  ed by.** subsequ
293e0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68  ent calls to oth
293f0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
29400 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e  ace functions.)^
29410 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29420 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74  te3_errstr() int
29430 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
29440 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  he English-langu
29450 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74  age text.** that
29460 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b   describes the [
29470 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73  result code], as
29480 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d   UTF-8..** ^(Mem
29490 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
294a0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
294b0 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
294c0 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e  internally.** an
294d0 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72  d must not be fr
294e0 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  eed by the appli
294f0 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20  cation)^..**.** 
29500 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69  When the seriali
29510 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
29520 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20  ode] is in use, 
29530 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a  it might be the.
29540 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73  ** case that a s
29550 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75  econd error occu
29560 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65  rs on a separate
29570 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65   thread in betwe
29580 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f  en.** the time o
29590 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f  f the first erro
295a0 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74  r and the call t
295b0 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
295c0 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74  es..** When that
295d0 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65   happens, the se
295e0 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20  cond error will 
295f0 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63  be reported sinc
29600 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72  e these.** inter
29610 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70  faces always rep
29620 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ort the most rec
29630 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20  ent result.  To 
29640 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65  avoid.** this, e
29650 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f  ach thread can o
29660 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20  btain exclusive 
29670 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
29680 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
29690 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e   D.** by invokin
296a0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
296b0 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33  _enter]([sqlite3
296c0 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62  _db_mutex](D)) b
296d0 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a  efore beginning.
296e0 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20  ** to use D and 
296f0 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
29700 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b  3_mutex_leave]([
29710 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
29720 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61  ](D)) after.** a
29730 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ll calls to the 
29740 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65  interfaces liste
29750 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c  d here are compl
29760 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  eted..**.** If a
29770 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  n interface fail
29780 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49  s with SQLITE_MI
29790 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73  SUSE, that means
297a0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
297b0 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e  * was invoked in
297c0 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65  correctly by the
297d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49   application.  I
297e0 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65  n that case, the
297f0 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61  .** error code a
29800 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f  nd message may o
29810 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74  r may not be set
29820 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
29830 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
29840 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74   *db);.int sqlit
29850 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
29860 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
29870 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
29880 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
29890 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
298a0 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
298b0 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
298c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
298d0 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b  te3_errstr(int);
298e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
298f0 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  : Prepared State
29900 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ment Object.** K
29910 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
29920 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
29930 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29940 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
29950 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
29960 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
29970 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
29980 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68  tement that.** h
29990 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64  as been compiled
299a0 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72   into binary for
299b0 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74  m and is ready t
299c0 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a  o be evaluated..
299d0 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65  **.** Think of e
299e0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
299f0 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20  t as a separate 
29a00 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d  computer program
29a10 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  .  The.** origin
29a20 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73  al SQL text is s
29a30 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70  ource code.  A p
29a40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29a50 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20  t object .** is 
29a60 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a  the compiled obj
29a70 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53  ect code.  All S
29a80 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  QL must be conve
29a90 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70  rted into a.** p
29aa0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29ab0 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20  t before it can 
29ac0 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  be run..**.** Th
29ad0 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20  e life-cycle of 
29ae0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
29af0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61  ment object usua
29b00 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68  lly goes like th
29b10 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
29b20 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
29b30 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
29b40 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e  ment object usin
29b50 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
29b60 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69  re_v2()]..** <li
29b70 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
29b80 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73   [parameters] us
29b90 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
29ba0 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
29bb0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
29bc0 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
29bd0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
29be0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
29bf0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
29c00 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
29c10 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
29c20 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
29c30 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65  te3_reset()] the
29c40 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20  n go back.**    
29c50 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f    to step 2.  Do
29c60 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   this zero or mo
29c70 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
29c80 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62  > Destroy the ob
29c90 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
29ca0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
29cb0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70  .** </ol>.*/.typ
29cc0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
29cd0 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
29ce0 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
29cf0 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
29d00 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f   Limits.** METHO
29d10 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
29d20 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
29d30 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
29d40 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
29d50 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
29d60 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
29d70 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
29d80 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
29d90 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
29da0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
29db0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
29dc0 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
29dd0 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
29de0 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
29df0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
29e00 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
29e10 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
29e20 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
29e30 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
29e40 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
29e50 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
29e60 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
29e70 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
29e80 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
29e90 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
29ea0 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
29eb0 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
29ec0 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
29ed0 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
29ee0 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
29ef0 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
29f00 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
29f10 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
29f20 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
29f30 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
29f40 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
29f50 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
29f60 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
29f70 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
29f80 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
29f90 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
29fa0 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
29fb0 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
29fc0 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
29fd0 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
29fe0 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
29ff0 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
2a000 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
2a010 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
2a020 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
2a030 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
2a040 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
2a050 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
2a060 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
2a070 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
2a080 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
2a090 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
2a0a0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2a0b0 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
2a0c0 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
2a0d0 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
2a0e0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
2a0f0 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
2a100 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
2a110 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
2a120 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
2a130 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
2a140 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
2a150 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
2a160 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
2a170 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
2a180 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
2a190 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
2a1a0 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
2a1b0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
2a1c0 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
2a1d0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
2a1e0 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
2a1f0 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
2a200 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
2a210 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
2a220 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
2a230 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
2a240 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
2a250 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
2a260 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
2a270 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
2a280 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
2a290 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
2a2a0 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
2a2b0 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
2a2c0 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
2a2d0 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
2a2e0 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
2a2f0 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
2a300 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
2a310 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
2a320 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
2a330 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
2a340 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
2a350 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
2a360 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
2a370 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
2a380 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
2a390 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
2a3a0 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
2a3b0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
2a3c0 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
2a3d0 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
2a3e0 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
2a3f0 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
2a400 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
2a410 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
2a420 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
2a430 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
2a440 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
2a450 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
2a460 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
2a470 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
2a480 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
2a490 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
2a4a0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
2a4b0 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ses..*/.int sqli
2a4c0 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
2a4d0 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
2a4e0 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
2a4f0 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
2a500 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
2a510 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
2a520 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
2a530 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
2a540 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
2a550 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
2a560 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
2a570 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
2a580 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
2a590 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
2a5a0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2a5b0 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
2a5c0 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
2a5d0 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
2a5e0 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
2a5f0 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
2a600 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
2a610 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
2a620 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
2a630 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
2a640 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
2a650 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  >.** [[SQLITE_LI
2a660 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  MIT_LENGTH]] ^(<
2a670 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2a680 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
2a690 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
2a6a0 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
2a6b0 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
2a6c0 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73  le row, in bytes
2a6d0 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  .<dd>)^.**.** [[
2a6e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
2a6f0 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
2a700 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
2a710 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
2a720 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2a730 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
2a740 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
2a750 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
2a760 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2a770 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74  T_COLUMN]] ^(<dt
2a780 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
2a790 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
2a7a0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
2a7b0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2a7c0 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
2a7d0 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
2a7e0 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
2a7f0 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
2a800 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2a810 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
2a820 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
2a830 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
2a840 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
2a850 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2a860 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
2a870 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
2a880 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
2a890 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
2a8a0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2a8b0 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
2a8c0 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
2a8d0 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29  xpression.</dd>)
2a8e0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2a8f0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
2a900 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53  SELECT]] ^(<dt>S
2a910 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
2a920 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
2a930 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2a940 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
2a950 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
2a960 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
2a970 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
2a980 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2a990 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e  VDBE_OP]] ^(<dt>
2a9a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
2a9b0 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
2a9c0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
2a9d0 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
2a9e0 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
2a9f0 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
2aa00 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
2aa10 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
2aa20 74 65 6d 65 6e 74 2e 20 20 49 66 20 5b 73 71 6c  tement.  If [sql
2aa30 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2aa40 29 5d 20 6f 72 0a 2a 2a 20 74 68 65 20 65 71 75  )] or.** the equ
2aa50 69 76 61 6c 65 6e 74 20 74 72 69 65 73 20 74 6f  ivalent tries to
2aa60 20 61 6c 6c 6f 63 61 74 65 20 73 70 61 63 65 20   allocate space 
2aa70 66 6f 72 20 6d 6f 72 65 20 74 68 61 6e 20 74 68  for more than th
2aa80 69 73 20 6d 61 6e 79 20 6f 70 63 6f 64 65 73 0a  is many opcodes.
2aa90 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c 65 20 70  ** in a single p
2aaa0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2aab0 74 2c 20 61 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d  t, an SQLITE_NOM
2aac0 45 4d 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  EM error is retu
2aad0 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
2aae0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2aaf0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d  T_FUNCTION_ARG]]
2ab00 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2ab10 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
2ab20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2ab30 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
2ab40 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
2ab50 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
2ab60 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2ab70 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
2ab80 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2ab90 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
2aba0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2abb0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2abc0 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63   [ATTACH | attac
2abd0 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29  hed databases].)
2abe0 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ^</dd>.**.** [[S
2abf0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
2ac00 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d  _PATTERN_LENGTH]
2ac10 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
2ac20 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
2ac30 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
2ac40 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2ac50 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
2ac60 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
2ac70 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d  nt to the [LIKE]
2ac80 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70   or.** [GLOB] op
2ac90 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a  erators.</dd>)^.
2aca0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2acb0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
2acc0 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  MBER]].** ^(<dt>
2acd0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
2ace0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
2acf0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2ad00 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65  imum index numbe
2ad10 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65  r of any [parame
2ad20 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73  ter] in an SQL s
2ad30 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a  tatement.)^.**.*
2ad40 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2ad50 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d  _TRIGGER_DEPTH]]
2ad60 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2ad70 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
2ad80 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
2ad90 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
2ada0 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72  of recursion for
2adb0 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29   triggers.</dd>)
2adc0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2add0 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
2ade0 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51  READS]] ^(<dt>SQ
2adf0 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
2ae00 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a  R_THREADS</dt>.*
2ae10 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2ae20 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69  m number of auxi
2ae30 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72  liary worker thr
2ae40 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67  eads that a sing
2ae50 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  le.** [prepared 
2ae60 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73  statement] may s
2ae70 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  tart.</dd>)^.** 
2ae80 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
2ae90 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
2aea0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
2aeb0 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
2aec0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
2aed0 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
2aee0 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
2aef0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2af00 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
2af10 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
2af20 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2af30 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
2af40 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
2af50 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2af60 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
2af70 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
2af80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2af90 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
2afa0 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
2afb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2afc0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
2afd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
2afe0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2aff0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
2b000 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
2b010 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2b020 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
2b030 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
2b040 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
2b050 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
2b060 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
2b070 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
2b080 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
2b090 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
2b0a0 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
2b0b0 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
2b0c0 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20  THREADS         
2b0d0 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    11../*.** CAPI
2b0e0 33 52 45 46 3a 20 50 72 65 70 61 72 65 20 46 6c  3REF: Prepare Fl
2b0f0 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ags.**.** These 
2b100 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
2b110 20 76 61 72 69 6f 75 73 20 66 6c 61 67 73 20 74   various flags t
2b120 68 61 74 20 63 61 6e 20 62 65 20 70 61 73 73 65  hat can be passe
2b130 64 20 69 6e 74 6f 0a 2a 2a 20 22 70 72 65 70 46  d into.** "prepF
2b140 6c 61 67 73 22 20 70 61 72 61 6d 65 74 65 72 20  lags" parameter 
2b150 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2b160 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 61 6e  prepare_v3()] an
2b170 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  d.** [sqlite3_pr
2b180 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20 69 6e  epare16_v3()] in
2b190 74 65 72 66 61 63 65 73 2e 0a 2a 2a 0a 2a 2a 20  terfaces..**.** 
2b1a0 4e 65 77 20 66 6c 61 67 73 20 6d 61 79 20 62 65  New flags may be
2b1b0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
2b1c0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
2b1d0 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ite..**.** <dl>.
2b1e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 52 45 50  ** [[SQLITE_PREP
2b1f0 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 5d 5d  ARE_PERSISTENT]]
2b200 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52   ^(<dt>SQLITE_PR
2b210 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54  EPARE_PERSISTENT
2b220 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2b230 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f   SQLITE_PREPARE_
2b240 50 45 52 53 49 53 54 45 4e 54 20 66 6c 61 67 20  PERSISTENT flag 
2b250 69 73 20 61 20 68 69 6e 74 20 74 6f 20 74 68 65  is a hint to the
2b260 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 0a 2a   query planner.*
2b270 2a 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61  * that the prepa
2b280 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 77 69  red statement wi
2b290 6c 6c 20 62 65 20 72 65 74 61 69 6e 65 64 20 66  ll be retained f
2b2a0 6f 72 20 61 20 6c 6f 6e 67 20 74 69 6d 65 20 61  or a long time a
2b2b0 6e 64 0a 2a 2a 20 70 72 6f 62 61 62 6c 79 20 72  nd.** probably r
2b2c0 65 75 73 65 64 20 6d 61 6e 79 20 74 69 6d 65 73  eused many times
2b2d0 2e 29 5e 20 5e 57 69 74 68 6f 75 74 20 74 68 69  .)^ ^Without thi
2b2e0 73 20 66 6c 61 67 2c 20 5b 73 71 6c 69 74 65 33  s flag, [sqlite3
2b2f0 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 0a 2a  _prepare_v3()].*
2b300 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  * and [sqlite3_p
2b310 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20 61  repare16_v3()] a
2b320 73 73 75 6d 65 20 74 68 61 74 20 74 68 65 20 70  ssume that the p
2b330 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b340 74 20 77 69 6c 6c 20 0a 2a 2a 20 62 65 20 75 73  t will .** be us
2b350 65 64 20 6a 75 73 74 20 6f 6e 63 65 20 6f 72 20  ed just once or 
2b360 61 74 20 6d 6f 73 74 20 61 20 66 65 77 20 74 69  at most a few ti
2b370 6d 65 73 20 61 6e 64 20 74 68 65 6e 20 64 65 73  mes and then des
2b380 74 72 6f 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20  troyed using.** 
2b390 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2b3a0 65 28 29 5d 20 72 65 6c 61 74 69 76 65 6c 79 20  e()] relatively 
2b3b0 73 6f 6f 6e 2e 20 54 68 65 20 63 75 72 72 65 6e  soon. The curren
2b3c0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
2b3d0 20 61 63 74 73 0a 2a 2a 20 6f 6e 20 74 68 69 73   acts.** on this
2b3e0 20 68 69 6e 74 20 62 79 20 61 76 6f 69 64 69 6e   hint by avoidin
2b3f0 67 20 74 68 65 20 75 73 65 20 6f 66 20 5b 6c 6f  g the use of [lo
2b400 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 5d 20  okaside memory] 
2b410 73 6f 20 61 73 20 6e 6f 74 20 74 6f 0a 2a 2a 20  so as not to.** 
2b420 64 65 70 6c 65 74 65 20 74 68 65 20 6c 69 6d 69  deplete the limi
2b430 74 65 64 20 73 74 6f 72 65 20 6f 66 20 6c 6f 6f  ted store of loo
2b440 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 20 46  kaside memory. F
2b450 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
2b460 66 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 79 20  f.** SQLite may 
2b470 61 63 74 20 6f 6e 20 74 68 69 73 20 68 69 6e 74  act on this hint
2b480 20 64 69 66 66 65 72 65 6e 74 6c 79 2e 0a 2a 2a   differently..**
2b490 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
2b4a0 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  e SQLITE_PREPARE
2b4b0 5f 50 45 52 53 49 53 54 45 4e 54 20 20 20 20 20  _PERSISTENT     
2b4c0 20 20 20 20 20 20 20 20 20 30 78 30 31 0a 0a 2f           0x01../
2b4d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2b4e0 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
2b4f0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59  Statement.** KEY
2b500 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
2b510 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
2b520 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2b530 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f  e3.** CONSTRUCTO
2b540 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  R: sqlite3_stmt.
2b550 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
2b560 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
2b570 74 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74  t, it must first
2b580 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74   be compiled int
2b590 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a  o a byte-code.**
2b5a0 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f   program using o
2b5b0 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ne of these rout
2b5c0 69 6e 65 73 2e 20 20 4f 72 2c 20 69 6e 20 6f 74  ines.  Or, in ot
2b5d0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 73 65  her words, these
2b5e0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
2b5f0 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 20 66 6f   constructors fo
2b600 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2b610 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
2b620 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  t..**.** The pre
2b630 66 65 72 72 65 64 20 72 6f 75 74 69 6e 65 20 74  ferred routine t
2b640 6f 20 75 73 65 20 69 73 20 5b 73 71 6c 69 74 65  o use is [sqlite
2b650 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e  3_prepare_v2()].
2b660 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
2b670 33 5f 70 72 65 70 61 72 65 28 29 5d 20 69 6e 74  3_prepare()] int
2b680 65 72 66 61 63 65 20 69 73 20 6c 65 67 61 63 79  erface is legacy
2b690 20 61 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 61   and should be a
2b6a0 76 6f 69 64 65 64 2e 0a 2a 2a 20 5b 73 71 6c 69  voided..** [sqli
2b6b0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2b6c0 5d 20 68 61 73 20 61 6e 20 65 78 74 72 61 20 22  ] has an extra "
2b6d0 70 72 65 70 46 6c 61 67 73 22 20 6f 70 74 69 6f  prepFlags" optio
2b6e0 6e 20 74 68 61 74 20 69 73 20 75 73 65 64 0a 2a  n that is used.*
2b6f0 2a 20 66 6f 72 20 73 70 65 63 69 61 6c 20 70 75  * for special pu
2b700 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  rposes..**.** Th
2b710 65 20 75 73 65 20 6f 66 20 74 68 65 20 55 54 46  e use of the UTF
2b720 2d 38 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  -8 interfaces is
2b730 20 70 72 65 66 65 72 72 65 64 2c 20 61 73 20 53   preferred, as S
2b740 51 4c 69 74 65 20 63 75 72 72 65 6e 74 6c 79 0a  QLite currently.
2b750 2a 2a 20 64 6f 65 73 20 61 6c 6c 20 70 61 72 73  ** does all pars
2b760 69 6e 67 20 75 73 69 6e 67 20 55 54 46 2d 38 2e  ing using UTF-8.
2b770 20 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74    The UTF-16 int
2b780 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
2b790 69 64 65 64 0a 2a 2a 20 61 73 20 61 20 63 6f 6e  ided.** as a con
2b7a0 76 65 6e 69 65 6e 63 65 2e 20 20 54 68 65 20 55  venience.  The U
2b7b0 54 46 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73  TF-16 interfaces
2b7c0 20 77 6f 72 6b 20 62 79 20 63 6f 6e 76 65 72 74   work by convert
2b7d0 69 6e 67 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74  ing the.** input
2b7e0 20 74 65 78 74 20 69 6e 74 6f 20 55 54 46 2d 38   text into UTF-8
2b7f0 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 69 6e 67 20  , then invoking 
2b800 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
2b810 67 20 55 54 46 2d 38 20 69 6e 74 65 72 66 61 63  g UTF-8 interfac
2b820 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  e..**.** The fir
2b830 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
2b840 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
2b850 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
2b860 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
2b870 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
2b880 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
2b890 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
2b8a0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
2b8b0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
2b8c0 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64  pen16()].  The d
2b8d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2b8e0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65  on must not have
2b8f0 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a   been closed..**
2b900 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
2b910 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
2b920 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
2b930 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
2b940 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
2b950 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
2b960 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
2b970 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 2c 20  ite3_prepare(), 
2b980 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2b990 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c  v2(),.** and sql
2b9a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2b9b0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
2b9c0 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73  use UTF-8, and s
2b9d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2b9e0 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70  (), sqlite3_prep
2b9f0 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61  are16_v2(),.** a
2ba00 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
2ba10 72 65 31 36 5f 76 33 28 29 20 75 73 65 20 55 54  re16_v3() use UT
2ba20 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  F-16..**.** ^If 
2ba30 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
2ba40 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  nt is negative, 
2ba50 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61  then zSql is rea
2ba60 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66  d up to the.** f
2ba70 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
2ba80 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20  ator. ^If nByte 
2ba90 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65  is positive, the
2baa0 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e  n it is the.** n
2bab0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 72  umber of bytes r
2bac0 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
2bad0 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72  ^If nByte is zer
2bae0 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61  o, then no prepa
2baf0 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
2bb00 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a   is generated..*
2bb10 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20  * If the caller 
2bb20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20 73  knows that the s
2bb30 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69  upplied string i
2bb40 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  s nul-terminated
2bb50 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20  , then.** there 
2bb60 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f  is a small perfo
2bb70 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65  rmance advantage
2bb80 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e   to passing an n
2bb90 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74  Byte parameter t
2bba0 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  hat.** is the nu
2bbb0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2bbc0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
2bbd0 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f  g <i>including</
2bbe0 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65  i>.** the nul-te
2bbf0 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
2bc00 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f  ^If pzTail is no
2bc10 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54  t NULL then *pzT
2bc20 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
2bc30 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
2bc40 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74  t byte.** past t
2bc50 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69  he end of the fi
2bc60 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
2bc70 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73  t in zSql.  Thes
2bc80 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a  e routines only.
2bc90 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66  ** compile the f
2bca0 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69  irst statement i
2bcb0 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61  n zSql, so *pzTa
2bcc0 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  il is left point
2bcd0 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72  ing to.** what r
2bce0 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65  emains uncompile
2bcf0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d  d..**.** ^*ppStm
2bd00 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  t is left pointi
2bd10 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64  ng to a compiled
2bd20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2bd30 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62  ment] that can b
2bd40 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73  e.** executed us
2bd50 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
2bd60 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65  p()].  ^If there
2bd70 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70   is an error, *p
2bd80 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20  pStmt is set.** 
2bd90 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68  to NULL.  ^If th
2bda0 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e  e input text con
2bdb0 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66  tains no SQL (if
2bdc0 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e   the input is an
2bdd0 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67   empty.** string
2bde0 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74   or a comment) t
2bdf0 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73  hen *ppStmt is s
2be00 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54  et to NULL..** T
2be10 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65  he calling proce
2be20 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69  dure is responsi
2be30 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67  ble for deleting
2be40 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a   the compiled.**
2be50 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75   SQL statement u
2be60 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
2be70 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20  nalize()] after 
2be80 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
2be90 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74  with it..** ppSt
2bea0 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55  mt may not be NU
2beb0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75  LL..**.** ^On su
2bec0 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74  ccess, the sqlit
2bed0 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d  e3_prepare() fam
2bee0 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20  ily of routines 
2bef0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
2bf00 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  K];.** otherwise
2bf10 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
2bf20 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2bf30 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2bf40 70 72 65 70 61 72 65 5f 76 32 28 29 2c 20 73 71  prepare_v2(), sq
2bf50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2bf60 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70  (), sqlite3_prep
2bf70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61  are16_v2(),.** a
2bf80 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
2bf90 72 65 31 36 5f 76 33 28 29 20 69 6e 74 65 72 66  re16_v3() interf
2bfa0 61 63 65 73 20 61 72 65 20 72 65 63 6f 6d 6d 65  aces are recomme
2bfb0 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
2bfc0 20 70 72 6f 67 72 61 6d 73 2e 0a 2a 2a 20 54 68   programs..** Th
2bfd0 65 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  e older interfac
2bfe0 65 73 20 28 73 71 6c 69 74 65 33 5f 70 72 65 70  es (sqlite3_prep
2bff0 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
2c000 33 5f 70 72 65 70 61 72 65 31 36 28 29 29 0a 2a  3_prepare16()).*
2c010 2a 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66  * are retained f
2c020 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
2c030 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
2c040 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
2c050 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e  couraged..** ^In
2c060 20 74 68 65 20 22 76 58 22 20 69 6e 74 65 72 66   the "vX" interf
2c070 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
2c080 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
2c090 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
2c0a0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
2c0b0 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
2c0c0 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
2c0d0 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  the.** original 
2c0e0 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63  SQL text. This c
2c0f0 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
2c100 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
2c110 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
2c120 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  e differently in
2c130 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a   three ways:.**.
2c140 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a  ** <ol>.** <li>.
2c150 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62  ** ^If the datab
2c160 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
2c170 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
2c180 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
2c190 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
2c1a0 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
2c1b0 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
2c1c0 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
2c1d0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
2c1e0 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
2c1f0 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
2c200 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
2c210 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c   As many as [SQL
2c220 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52  ITE_MAX_SCHEMA_R
2c230 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73  ETRY].** retries
2c240 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f   will occur befo
2c250 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  re sqlite3_step(
2c260 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72  ) gives up and r
2c270 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e  eturns an error.
2c280 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
2c290 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e  <li>.** ^When an
2c2a0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b   error occurs, [
2c2b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2c2c0 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
2c2d0 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a  of the detailed.
2c2e0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
2c2f0 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
2c300 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68  ror codes].  ^Th
2c310 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
2c320 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73  r was that.** [s
2c330 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
2c340 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e  ould only return
2c350 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49   a generic [SQLI
2c360 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
2c370 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65   code.** and the
2c380 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75   application wou
2c390 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
2c3a0 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
2c3b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2c3c0 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74  )].** in order t
2c3d0 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
2c3e0 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
2c3f0 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68  he problem. With
2c400 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
2c410 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c  e.** interfaces,
2c420 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
2c430 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
2c440 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
2c450 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
2c460 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
2c470 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  >.** ^If the spe
2c480 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e  cific value boun
2c490 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20  d to [parameter 
2c4a0 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  | host parameter
2c4b0 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45  ] in the .** WHE
2c4c0 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20  RE clause might 
2c4d0 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68  influence the ch
2c4e0 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
2c4f0 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65  an for a stateme
2c500 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  nt,.** then the 
2c510 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62  statement will b
2c520 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
2c530 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69  recompiled, as i
2c540 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e  f there had been
2c550 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68   .** a schema ch
2c560 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72  ange, on the fir
2c570 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  st  [sqlite3_ste
2c580 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77  p()] call follow
2c590 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a  ing any change.*
2c5a0 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
2c5b0 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69  3_bind_text | bi
2c5c0 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20  ndings] of that 
2c5d0 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a  [parameter]. .**
2c5e0 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76   ^The specific v
2c5f0 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c  alue of WHERE-cl
2c600 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d  ause [parameter]
2c610 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
2c620 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20   the .** choice 
2c630 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66  of query plan if
2c640 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
2c650 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20  s the left-hand 
2c660 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d  side of a [LIKE]
2c670 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70  .** or [GLOB] op
2c680 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65  erator or if the
2c690 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f   parameter is co
2c6a0 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64  mpared to an ind
2c6b0 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  exed column.** a
2c6c0 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45  nd the [SQLITE_E
2c6d0 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d  NABLE_STAT3] com
2c6e0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
2c6f0 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20   is enabled..** 
2c700 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e 5e  </li>.**.** <p>^
2c710 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2c720 76 33 28 29 20 64 69 66 66 65 72 73 20 66 72 6f  v3() differs fro
2c730 6d 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  m sqlite3_prepar
2c740 65 5f 76 32 28 29 20 6f 6e 6c 79 20 69 6e 20 68  e_v2() only in h
2c750 61 76 69 6e 67 0a 2a 2a 20 74 68 65 20 65 78 74  aving.** the ext
2c760 72 61 20 70 72 65 70 46 6c 61 67 73 20 70 61 72  ra prepFlags par
2c770 61 6d 65 74 65 72 2c 20 77 68 69 63 68 20 69 73  ameter, which is
2c780 20 61 20 62 69 74 20 61 72 72 61 79 20 63 6f 6e   a bit array con
2c790 73 69 73 74 69 6e 67 20 6f 66 20 7a 65 72 6f 20  sisting of zero 
2c7a0 6f 72 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68  or.** more of th
2c7b0 65 20 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52  e [SQLITE_PREPAR
2c7c0 45 5f 50 45 52 53 49 53 54 45 4e 54 7c 53 51 4c  E_PERSISTENT|SQL
2c7d0 49 54 45 5f 50 52 45 50 41 52 45 5f 2a 5d 20 66  ITE_PREPARE_*] f
2c7e0 6c 61 67 73 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  lags.  ^The.** s
2c7f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2c800 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
2c810 72 6b 73 20 65 78 61 63 74 6c 79 20 74 68 65 20  rks exactly the 
2c820 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74  same as.** sqlit
2c830 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 20  e3_prepare_v3() 
2c840 77 69 74 68 20 61 20 7a 65 72 6f 20 70 72 65 70  with a zero prep
2c850 46 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 2e  Flags parameter.
2c860 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ol>.*/.int
2c870 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2c880 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2c890 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2c8a0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2c8b0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2c8c0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2c8d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2c8e0 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
2c8f0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2c900 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2c910 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2c920 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2c930 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2c940 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2c950 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2c960 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2c970 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
2c980 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2c990 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2c9a0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2c9b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
2c9c0 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
2c9d0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2c9e0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2c9f0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2ca00 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
2ca10 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2ca20 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
2ca30 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2ca40 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2ca50 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2ca60 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2ca70 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2ca80 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2ca90 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2caa0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2cab0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
2cac0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2cad0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2cae0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2caf0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
2cb00 33 5f 70 72 65 70 61 72 65 5f 76 33 28 0a 20 20  3_prepare_v3(.  
2cb10 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2cb20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2cb30 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
2cb40 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
2cb50 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
2cb60 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
2cb70 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2cb80 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2cb90 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2cba0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2cbb0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e  n bytes. */.  un
2cbc0 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46  signed int prepF
2cbd0 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72  lags, /* Zero or
2cbe0 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45   more SQLITE_PRE
2cbf0 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20  PARE_ flags */. 
2cc00 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2cc10 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2cc20 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2cc30 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2cc40 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
2cc50 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2cc60 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2cc70 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
2cc80 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2cc90 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
2cca0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2ccb0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2ccc0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2ccd0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
2cce0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2ccf0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
2cd00 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2cd10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2cd20 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2cd30 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2cd40 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2cd50 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2cd60 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2cd70 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2cd80 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
2cd90 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2cda0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2cdb0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2cdc0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2cdd0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
2cde0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2cdf0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2ce00 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2ce10 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
2ce20 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2ce30 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
2ce40 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
2ce50 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2ce60 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2ce70 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2ce80 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2ce90 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2cea0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2ceb0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2cec0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2ced0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2cee0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2cef0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2cf00 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
2cf10 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2cf20 65 31 36 5f 76 33 28 0a 20 20 73 71 6c 69 74 65  e16_v3(.  sqlite
2cf30 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2cf40 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2cf50 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2cf60 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
2cf70 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2cf80 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
2cf90 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2cfa0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2cfb0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2cfc0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2cfd0 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65  es. */.  unsigne
2cfe0 64 20 69 6e 74 20 70 72 65 70 46 6c 61 67 73 2c  d int prepFlags,
2cff0 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65   /* Zero or more
2d000 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f   SQLITE_PREPARE_
2d010 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69   flags */.  sqli
2d020 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2d030 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2d040 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2d050 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
2d060 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2d070 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2d080 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2d090 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  Sql */.);../*.**
2d0a0 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69   CAPI3REF: Retri
2d0b0 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20  eving Statement 
2d0c0 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  SQL.** METHOD: s
2d0d0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2d0e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2d0f0 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  ql(P) interface 
2d100 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2d110 72 20 74 6f 20 61 20 63 6f 70 79 20 6f 66 20 74  r to a copy of t
2d120 68 65 20 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20  he UTF-8.** SQL 
2d130 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
2d140 61 74 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ate [prepared st
2d150 61 74 65 6d 65 6e 74 5d 20 50 20 69 66 20 50 20  atement] P if P 
2d160 77 61 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  was.** created b
2d170 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
2d180 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
2d190 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
2d1a0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
2d1b0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f  epare16_v2()], o
2d1c0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2d1d0 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 20 5e  re16_v3()]..** ^
2d1e0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61  The sqlite3_expa
2d1f0 6e 64 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 65  nded_sql(P) inte
2d200 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2d210 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46  pointer to a UTF
2d220 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  -8.** string con
2d230 74 61 69 6e 69 6e 67 20 74 68 65 20 53 51 4c 20  taining the SQL 
2d240 74 65 78 74 20 6f 66 20 70 72 65 70 61 72 65 64  text of prepared
2d250 20 73 74 61 74 65 6d 65 6e 74 20 50 20 77 69 74   statement P wit
2d260 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61  h.** [bound para
2d270 6d 65 74 65 72 73 5d 20 65 78 70 61 6e 64 65 64  meters] expanded
2d280 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  ..**.** ^(For ex
2d290 61 6d 70 6c 65 2c 20 69 66 20 61 20 70 72 65 70  ample, if a prep
2d2a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2d2b0 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  s created using 
2d2c0 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20  the SQL.** text 
2d2d0 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79  "SELECT $abc,:xy
2d2e0 7a 22 20 61 6e 64 20 69 66 20 70 61 72 61 6d 65  z" and if parame
2d2f0 74 65 72 20 24 61 62 63 20 69 73 20 62 6f 75 6e  ter $abc is boun
2d300 64 20 74 6f 20 69 6e 74 65 67 65 72 20 32 33 34  d to integer 234
2d310 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61 6d 65 74  5.** and paramet
2d320 65 72 20 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75  er :xyz is unbou
2d330 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  nd, then sqlite3
2d340 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72 65 74 75  _sql() will retu
2d350 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  rn.** the origin
2d360 61 6c 20 73 74 72 69 6e 67 2c 20 22 53 45 4c 45  al string, "SELE
2d370 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 62 75  CT $abc,:xyz" bu
2d380 74 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  t sqlite3_expand
2d390 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c  ed_sql().** will
2d3a0 20 72 65 74 75 72 6e 20 22 53 45 4c 45 43 54 20   return "SELECT 
2d3b0 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a  2345,NULL".)^.**
2d3c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2d3d0 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20  _expanded_sql() 
2d3e0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2d3f0 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66  s NULL if insuff
2d400 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a  icient memory.**
2d410 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f   is available to
2d420 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
2d430 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 73 75  , or if the resu
2d440 6c 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20  lt would exceed 
2d450 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d  the.** the maxim
2d460 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e 67 74 68  um string length
2d470 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
2d480 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  he [SQLITE_LIMIT
2d490 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20  _LENGTH]..**.** 
2d4a0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  ^The [SQLITE_TRA
2d4b0 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63  CE_SIZE_LIMIT] c
2d4c0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
2d4d0 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65 20 73 69  on limits the si
2d4e0 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70  ze of.** bound p
2d4f0 61 72 61 6d 65 74 65 72 20 65 78 70 61 6e 73 69  arameter expansi
2d500 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  ons.  ^The [SQLI
2d510 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63  TE_OMIT_TRACE] c
2d520 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
2d530 70 74 69 6f 6e 20 63 61 75 73 65 73 20 73 71 6c  ption causes sql
2d540 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2d550 6c 28 29 20 74 6f 20 61 6c 77 61 79 73 20 72 65  l() to always re
2d560 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  turn NULL..**.**
2d570 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72 65 74   ^The string ret
2d580 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2d590 5f 73 71 6c 28 50 29 20 69 73 20 6d 61 6e 61 67  _sql(P) is manag
2d5a0 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64  ed by SQLite and
2d5b0 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   is.** automatic
2d5c0 61 6c 6c 79 20 66 72 65 65 64 20 77 68 65 6e 20  ally freed when 
2d5d0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
2d5e0 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69  tement is finali
2d5f0 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72  zed..** ^The str
2d600 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20  ing returned by 
2d610 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2d620 5f 73 71 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20  _sql(P), on the 
2d630 6f 74 68 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69  other hand,.** i
2d640 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
2d650 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
2d660 29 5d 20 61 6e 64 20 6d 75 73 74 20 62 65 20 66  )] and must be f
2d670 72 65 65 20 62 79 20 74 68 65 20 61 70 70 6c 69  ree by the appli
2d680 63 61 74 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73  cation.** by pas
2d690 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
2d6a0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a  te3_free()]..*/.
2d6b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2d6c0 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  te3_sql(sqlite3_
2d6d0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 63 68  stmt *pStmt);.ch
2d6e0 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 78 70 61  ar *sqlite3_expa
2d6f0 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69 74 65 33  nded_sql(sqlite3
2d700 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2d710 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d720 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
2d730 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72  SQL Statement Wr
2d740 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73  ites The Databas
2d750 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  e.** METHOD: sql
2d760 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2d770 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
2d780 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e  t_readonly(X) in
2d790 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2d7a0 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
2d7b0 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69  if.** and only i
2d7c0 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
2d7d0 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b  statement] X mak
2d7e0 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61  es no direct cha
2d7f0 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63  nges to.** the c
2d800 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
2d810 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a  tabase file..**.
2d820 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70  ** Note that [ap
2d830 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2d840 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
2d850 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20   or.** [virtual 
2d860 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68  tables] might ch
2d870 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
2d880 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20  e indirectly as 
2d890 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20  a side effect.  
2d8a0 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
2d8b0 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  e, if an applica
2d8c0 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66  tion defines a f
2d8d0 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22  unction "eval()"
2d8e0 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20   that .** calls 
2d8f0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
2d900 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f  , then the follo
2d910 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  wing SQL stateme
2d920 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e  nt would.** chan
2d930 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
2d940 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64  file through sid
2d950 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a  e-effects:.**.**
2d960 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
2d970 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20  e>.**    SELECT 
2d980 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f  eval('DELETE FRO
2d990 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a  M t1') FROM t2;.
2d9a0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
2d9b0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74  quote>.**.** But
2d9c0 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45   because the [SE
2d9d0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
2d9e0 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
2d9f0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2da00 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73  e.** directly, s
2da10 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2da20 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69  only() would sti
2da30 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29  ll return true.)
2da40 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63  ^.**.** ^Transac
2da50 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61  tion control sta
2da60 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20  tements such as 
2da70 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54  [BEGIN], [COMMIT
2da80 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a  ], [ROLLBACK],.*
2da90 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61  * [SAVEPOINT], a
2daa0 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75  nd [RELEASE] cau
2dab0 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  se sqlite3_stmt_
2dac0 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
2dad0 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69  turn true,.** si
2dae0 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  nce the statemen
2daf0 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f  ts themselves do
2db00 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f   not actually mo
2db10 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
2db20 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20  e but.** rather 
2db30 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65  they control the
2db40 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20   timing of when 
2db50 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73  other statements
2db60 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20   modify the .** 
2db70 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20  database.  ^The 
2db80 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45  [ATTACH] and [DE
2db90 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73  TACH] statements
2dba0 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73   also cause.** s
2dbb0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2dbc0 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
2dbd0 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69   true since, whi
2dbe0 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65  le those stateme
2dbf0 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  nts.** change th
2dc00 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
2dc10 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  of a database co
2dc20 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64  nnection, they d
2dc30 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63  o not make .** c
2dc40 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f  hanges to the co
2dc50 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
2dc60 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64  abase files on d
2dc70 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  isk..** ^The sql
2dc80 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2dc90 6c 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ly() interface r
2dca0 65 74 75 72 6e 73 20 74 72 75 65 20 66 6f 72 20  eturns true for 
2dcb0 5b 42 45 47 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a  [BEGIN] since.**
2dcc0 20 5b 42 45 47 49 4e 5d 20 6d 65 72 65 6c 79 20   [BEGIN] merely 
2dcd0 73 65 74 73 20 69 6e 74 65 72 6e 61 6c 20 66 6c  sets internal fl
2dce0 61 67 73 2c 20 62 75 74 20 74 68 65 20 5b 42 45  ags, but the [BE
2dcf0 47 49 4e 7c 42 45 47 49 4e 20 49 4d 4d 45 44 49  GIN|BEGIN IMMEDI
2dd00 41 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45 47  ATE] and.** [BEG
2dd10 49 4e 7c 42 45 47 49 4e 20 45 58 43 4c 55 53 49  IN|BEGIN EXCLUSI
2dd20 56 45 5d 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 20  VE] commands do 
2dd30 74 6f 75 63 68 20 74 68 65 20 64 61 74 61 62 61  touch the databa
2dd40 73 65 20 61 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c  se and so.** sql
2dd50 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2dd60 6c 79 28 29 20 72 65 74 75 72 6e 73 20 66 61 6c  ly() returns fal
2dd70 73 65 20 66 6f 72 20 74 68 6f 73 65 20 63 6f 6d  se for those com
2dd80 6d 61 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  mands..*/.int sq
2dd90 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2dda0 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  nly(sqlite3_stmt
2ddb0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2ddc0 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
2ddd0 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72  mine If A Prepar
2dde0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73  ed Statement Has
2ddf0 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d   Been Reset.** M
2de00 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2de10 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
2de20 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
2de30 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (S) interface re
2de40 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
2de50 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20  zero) if the.** 
2de60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2de70 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20  ent] S has been 
2de80 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74  stepped at least
2de90 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20   once using .** 
2dea0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2deb0 5d 20 62 75 74 20 68 61 73 20 6e 65 69 74 68 65  ] but has neithe
2dec0 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74  r run to complet
2ded0 69 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a  ion (returned.**
2dee0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66   [SQLITE_DONE] f
2def0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rom [sqlite3_ste
2df00 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65  p(S)]) nor.** be
2df10 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b  en reset using [
2df20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2df30 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
2df40 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a  _stmt_busy(S).**
2df50 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2df60 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73  ns false if S is
2df70 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2df80 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20    If S is not a 
2df90 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
2dfa0 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f   and is not a po
2dfb0 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64  inter to a valid
2dfc0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2dfd0 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c  ment].** object,
2dfe0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2dff0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  or is undefined 
2e000 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
2e010 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  esirable..**.** 
2e020 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
2e030 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f  an be used in co
2e040 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74  mbination [sqlit
2e050 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a  e3_next_stmt()].
2e060 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c  ** to locate all
2e070 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2e080 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
2e090 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20  with a database 
2e0a0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
2e0b0 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20  hat are in need 
2e0c0 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20  of being reset. 
2e0d0 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65   This can be use
2e0e0 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c  d,.** for exampl
2e0f0 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63  e, in diagnostic
2e100 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61   routines to sea
2e110 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64  rch for prepared
2e120 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20   .** statements 
2e130 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67  that are holding
2e140 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f   a transaction o
2e150 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  pen..*/.int sqli
2e160 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71  te3_stmt_busy(sq
2e170 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2e180 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2e190 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64  ynamically Typed
2e1a0 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a   Value Object.**
2e1b0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74   KEYWORDS: {prot
2e1c0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e1d0 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65  lue} {unprotecte
2e1e0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
2e1f0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
2e200 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  es the sqlite3_v
2e210 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72  alue object to r
2e220 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c  epresent all val
2e230 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  ues.** that can 
2e240 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64  be stored in a d
2e250 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53  atabase table. S
2e260 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
2e270 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72  ic typing.** for
2e280 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73   the values it s
2e290 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20  tores.  ^Values 
2e2a0 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65  stored in sqlite
2e2b0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a  3_value objects.
2e2c0 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65  ** can be intege
2e2d0 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rs, floating poi
2e2e0 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e  nt values, strin
2e2f0 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55  gs, BLOBs, or NU
2e300 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c  LL..**.** An sql
2e310 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2e320 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20  t may be either 
2e330 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22  "protected" or "
2e340 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a  unprotected"..**
2e350 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73   Some interfaces
2e360 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65   require a prote
2e370 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2e380 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72  ue.  Other inter
2e390 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63  faces.** will ac
2e3a0 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72  cept either a pr
2e3b0 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e  otected or an un
2e3c0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2e3d0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72  3_value..** Ever
2e3e0 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
2e3f0 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33   accepts sqlite3
2e400 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73  _value arguments
2e410 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
2e420 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
2e430 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65  requires a prote
2e440 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2e450 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  ue.  The.** [sql
2e460 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29  ite3_value_dup()
2e470 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  ] interface can 
2e480 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74  be used to const
2e490 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70  ruct a new .** p
2e4a0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2e4b0 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75  _value from an u
2e4c0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2e4d0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  e3_value..**.** 
2e4e0 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65  The terms "prote
2e4f0 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f  cted" and "unpro
2e500 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f  tected" refer to
2e510 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a   whether or not.
2e520 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65  ** a mutex is he
2e530 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c  ld.  An internal
2e540 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
2e550 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a  or a protected.*
2e560 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
2e570 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75  object but no mu
2e580 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
2e590 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  an unprotected.*
2e5a0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
2e5b0 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69  object.  If SQLi
2e5c0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74  te is compiled t
2e5d0 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65  o be single-thre
2e5e0 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53  aded.** (with [S
2e5f0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
2e600 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71  =0] and with [sq
2e610 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
2e620 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29  ()] returning 0)
2e630 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65  .** or if SQLite
2e640 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f   is run in one o
2e650 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20  f reduced mutex 
2e660 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  modes .** [SQLIT
2e670 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2e680 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54  HREAD] or [SQLIT
2e690 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
2e6a0 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  READ].** then th
2e6b0 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e  ere is no distin
2e6c0 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
2e6d0 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
2e6e0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
2e6f0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2e700 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65   and they can be
2e710 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67   used interchang
2e720 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c  eably.  However,
2e730 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  .** for maximum 
2e740 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79  code portability
2e750 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
2e760 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
2e770 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61  ions.** still ma
2e780 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
2e790 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
2e7a0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
2e7b0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
2e7c0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76  value objects ev
2e7d0 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69  en when not stri
2e7e0 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a  ctly required..*
2e7f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2e800 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
2e810 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20  that are passed 
2e820 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  as parameters in
2e830 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  to the.** implem
2e840 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70  entation of [app
2e850 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2e860 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
2e870 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a  are protected..*
2e880 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
2e890 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75  alue object retu
2e8a0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
2e8b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2e8c0 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74  ()] is unprotect
2e8d0 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74  ed..** Unprotect
2e8e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2e8f0 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c   objects may onl
2e900 79 20 62 65 20 75 73 65 64 20 61 73 20 61 72 67  y be used as arg
2e910 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 5b 73 71  uments.** to [sq
2e920 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2e930 75 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ue()], [sqlite3_
2e940 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2c 20 61  bind_value()], a
2e950 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  nd.** [sqlite3_v
2e960 61 6c 75 65 5f 64 75 70 28 29 5d 2e 0a 2a 2a 20  alue_dup()]..** 
2e970 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2e980 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  ue_blob | sqlite
2e990 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20  3_value_type()] 
2e9a0 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74  family of.** int
2e9b0 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
2e9c0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2e9d0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e  3_value objects.
2e9e0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
2e9f0 63 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ct sqlite3_value
2ea00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a   sqlite3_value;.
2ea10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ea20 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f   SQL Function Co
2ea30 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ntext Object.**.
2ea40 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69  ** The context i
2ea50 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66  n which an SQL f
2ea60 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73  unction executes
2ea70 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e   is stored in an
2ea80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  .** sqlite3_cont
2ea90 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20  ext object.  ^A 
2eaa0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71  pointer to an sq
2eab0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
2eac0 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79  ject.** is alway
2ead0 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
2eae0 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f  r to [applicatio
2eaf0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2eb00 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65  nctions]..** The
2eb10 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2eb20 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2eb30 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2eb40 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a   will pass this.
2eb50 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75  ** pointer throu
2eb60 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f  gh into calls to
2eb70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2eb80 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72  _int | sqlite3_r
2eb90 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  esult()],.** [sq
2eba0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2ebb0 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c  context()], [sql
2ebc0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
2ebd0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ],.** [sqlite3_c
2ebe0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
2ebf0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65  ()], [sqlite3_ge
2ec00 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a  t_auxdata()],.**
2ec10 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33   and/or [sqlite3
2ec20 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e  _set_auxdata()].
2ec30 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
2ec40 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ct sqlite3_conte
2ec50 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt sqlite3_conte
2ec60 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  xt;../*.** CAPI3
2ec70 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c  REF: Binding Val
2ec80 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20  ues To Prepared 
2ec90 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45  Statements.** KE
2eca0 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61  YWORDS: {host pa
2ecb0 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70  rameter} {host p
2ecc0 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74  arameters} {host
2ecd0 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d   parameter name}
2ece0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
2ecf0 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53  QL parameter} {S
2ed00 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  QL parameters} {
2ed10 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
2ed20 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  g}.** METHOD: sq
2ed30 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2ed40 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
2ed50 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
2ed60 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
2ed70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2ed80 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
2ed90 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
2eda0 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
2edb0 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
2edc0 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
2edd0 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
2ede0 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
2edf0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
2ee00 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
2ee10 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
2ee20 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
2ee30 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
2ee40 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
2ee50 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
2ee60 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
2ee70 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
2ee80 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
2ee90 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
2eea0 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
2eeb0 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  .)^  ^The values
2eec0 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72   of these.** par
2eed0 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
2eee0 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
2eef0 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22  eter names" or "
2ef00 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
2ef10 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
2ef20 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
2ef30 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2ef40 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
2ef50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2ef60 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
2ef70 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2ef80 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
2ef90 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
2efa0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
2efb0 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
2efc0 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
2efd0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2efe0 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
2eff0 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ariants..**.** ^
2f000 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
2f010 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
2f020 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
2f030 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
2f040 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  .** ^The leftmos
2f050 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
2f060 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
2f070 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61  1.  ^When the sa
2f080 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
2f090 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
2f0a0 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
2f0b0 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
2f0c0 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
2f0d0 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
2f0e0 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
2f0f0 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
2f100 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65  ce..** ^The inde
2f110 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
2f120 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
2f130 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
2f140 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
2f150 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2f160 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
2f170 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65  ired.  ^The inde
2f180 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
2f190 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
2f1a0 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
2f1b0 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75  ** ^The NNN valu
2f1c0 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
2f1d0 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
2f1e0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
2f1f0 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
2f200 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
2f210 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
2f220 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
2f230 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
2f240 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
2f250 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
2f260 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
2f270 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
2f280 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
2f290 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2f2a0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
2f2b0 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f  nd_text16().** o
2f2c0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  r sqlite3_bind_b
2f2d0 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  lob() is a NULL 
2f2e0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
2f2f0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2f300 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20  r.** is ignored 
2f310 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75  and the end resu
2f320 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  lt is the same a
2f330 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  s sqlite3_bind_n
2f340 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ull()..**.** ^(I
2f350 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73  n those routines
2f360 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75   that have a fou
2f370 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74  rth argument, it
2f380 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  s value is the.*
2f390 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
2f3a0 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  s in the paramet
2f3b0 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72  er.  To be clear
2f3c0 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74  : the value is t
2f3d0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2f3e0 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20  <u>bytes</u> in 
2f3f0 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74  the value, not t
2f400 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
2f410 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49  racters.)^.** ^I
2f420 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2f430 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2f440 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
2f450 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2f460 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67  xt16().** is neg
2f470 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
2f480 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
2f490 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e  ring is.** the n
2f4a0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
2f4b0 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
2f4c0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
2f4d0 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  ** If the fourth
2f4e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2f4f0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2f500 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  ) is negative, t
2f510 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76  hen.** the behav
2f520 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
2f530 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65  ..** If a non-ne
2f540 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61  gative fourth pa
2f550 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69  rameter is provi
2f560 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ded to sqlite3_b
2f570 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72  ind_text().** or
2f580 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2f590 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65  xt16() or sqlite
2f5a0 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
2f5b0 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72  then.** that par
2f5c0 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74  ameter must be t
2f5d0 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a  he byte offset.*
2f5e0 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  * where the NUL 
2f5f0 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
2f600 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20   occur assuming 
2f610 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20  the string were 
2f620 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65  NUL.** terminate
2f630 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
2f640 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20  haracters occur 
2f650 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20  at byte offsets 
2f660 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68  less than .** th
2f670 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66  e value of the f
2f680 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2f690 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
2f6a0 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20  ng string value 
2f6b0 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  will.** contain 
2f6c0 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20  embedded NULs.  
2f6d0 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78  The result of ex
2f6e0 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76  pressions involv
2f6f0 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77  ing strings.** w
2f700 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
2f710 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
2f720 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
2f730 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2f740 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67   BLOB and string
2f750 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61   binding interfa
2f760 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74  ces.** is a dest
2f770 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
2f780 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
2f790 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
2f7a0 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
2f7b0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
2f7c0 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  t.  ^The destruc
2f7d0 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a  tor is called.**
2f7e0 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
2f7f0 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
2f800 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61  g even if the ca
2f810 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66  ll to bind API f
2f820 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ails..** ^If the
2f830 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2f840 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61  is.** the specia
2f850 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
2f860 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51  STATIC], then SQ
2f870 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
2f880 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  t the.** informa
2f890 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69  tion is in stati
2f8a0 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  c, unmanaged spa
2f8b0 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  ce and does not 
2f8c0 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64  need to be freed
2f8d0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
2f8e0 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  th argument has 
2f8f0 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  the value [SQLIT
2f900 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
2f910 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  en.** SQLite mak
2f920 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  es its own priva
2f930 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64  te copy of the d
2f940 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  ata immediately,
2f950 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73   before.** the s
2f960 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2f970 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e  routine returns.
2f980 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74  .**.** ^The sixt
2f990 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
2f9a0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2f9b0 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20  4() must be one 
2f9c0 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  of.** [SQLITE_UT
2f9d0 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
2f9e0 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  16], [SQLITE_UTF
2f9f0 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  16BE], or [SQLIT
2fa00 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f  E_UTF16LE].** to
2fa10 20 73 70 65 63 69 66 79 20 74 68 65 20 65 6e 63   specify the enc
2fa20 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78  oding of the tex
2fa30 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70  t in the third p
2fa40 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a  arameter.  If.**
2fa50 20 74 68 65 20 73 69 78 74 68 20 61 72 67 75 6d   the sixth argum
2fa60 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
2fa70 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73 20  ind_text64() is 
2fa80 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
2fa90 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73  * allowed values
2faa0 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72   shown above, or
2fab0 20 69 66 20 74 68 65 20 74 65 78 74 20 65 6e 63   if the text enc
2fac0 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
2fad0 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65  nt.** from the e
2fae0 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65  ncoding specifie
2faf0 64 20 62 79 20 74 68 65 20 73 69 78 74 68 20 70  d by the sixth p
2fb00 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74  arameter, then t
2fb10 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69  he behavior.** i
2fb20 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2fb30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2fb40 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
2fb50 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
2fb60 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
2fb70 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
2fb80 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20  ed with zeroes. 
2fb90 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65   ^A zeroblob use
2fba0 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
2fbb0 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
2fbc0 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
2fbd0 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
2fbe0 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
2fbf0 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
2fc00 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
2fc10 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
2fc20 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
2fc30 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
2fc40 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
2fc50 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
2fc60 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
2fc70 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
2fc80 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
2fc90 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41   routines..** ^A
2fca0 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
2fcb0 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
2fcc0 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
2fcd0 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
2fce0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2fcf0 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28  e3_bind_pointer(
2fd00 53 2c 49 2c 50 2c 54 2c 44 29 20 72 6f 75 74 69  S,I,P,T,D) routi
2fd10 6e 65 20 63 61 75 73 65 73 20 74 68 65 20 49 2d  ne causes the I-
2fd20 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 6e 0a  th parameter in.
2fd30 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2fd40 74 65 6d 65 6e 74 5d 20 53 20 74 6f 20 68 61 76  tement] S to hav
2fd50 65 20 61 6e 20 53 51 4c 20 76 61 6c 75 65 20 6f  e an SQL value o
2fd60 66 20 4e 55 4c 4c 2c 20 62 75 74 20 74 6f 20 61  f NULL, but to a
2fd70 6c 73 6f 20 62 65 0a 2a 2a 20 61 73 73 6f 63 69  lso be.** associ
2fd80 61 74 65 64 20 77 69 74 68 20 74 68 65 20 70 6f  ated with the po
2fd90 69 6e 74 65 72 20 50 20 6f 66 20 74 79 70 65 20  inter P of type 
2fda0 54 2e 20 20 5e 44 20 69 73 20 65 69 74 68 65 72  T.  ^D is either
2fdb0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2fdc0 6f 72 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  or.** a pointer 
2fdd0 74 6f 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  to a destructor 
2fde0 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 50 2e 20  function for P. 
2fdf0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76  ^SQLite will inv
2fe00 6f 6b 65 20 74 68 65 0a 2a 2a 20 64 65 73 74 72  oke the.** destr
2fe10 75 63 74 6f 72 20 44 20 77 69 74 68 20 61 20 73  uctor D with a s
2fe20 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
2fe30 66 20 50 20 77 68 65 6e 20 69 74 20 69 73 20 66  f P when it is f
2fe40 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a  inished using.**
2fe50 20 50 2e 20 20 54 68 65 20 54 20 70 61 72 61 6d   P.  The T param
2fe60 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61  eter should be a
2fe70 20 73 74 61 74 69 63 20 73 74 72 69 6e 67 2c 20   static string, 
2fe80 70 72 65 66 65 72 61 62 6c 79 20 61 20 73 74 72  preferably a str
2fe90 69 6e 67 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 20  ing.** literal. 
2fea0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2feb0 5f 70 6f 69 6e 74 65 72 28 29 20 72 6f 75 74 69  _pointer() routi
2fec0 6e 65 20 69 73 20 70 61 72 74 20 6f 66 20 74 68  ne is part of th
2fed0 65 0a 2a 2a 20 5b 70 6f 69 6e 74 65 72 20 70 61  e.** [pointer pa
2fee0 73 73 69 6e 67 20 69 6e 74 65 72 66 61 63 65 5d  ssing interface]
2fef0 20 61 64 64 65 64 20 66 6f 72 20 53 51 4c 69 74   added for SQLit
2ff00 65 20 33 2e 32 30 2e 30 2e 0a 2a 2a 0a 2a 2a 20  e 3.20.0..**.** 
2ff10 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73  ^If any of the s
2ff20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2ff30 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
2ff40 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
2ff50 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74  pointer.** for t
2ff60 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2ff70 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20  tement] or with 
2ff80 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
2ff90 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a  ment for which.*
2ffa0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2ffb0 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c  )] has been call
2ffc0 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79  ed more recently
2ffd0 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72   than [sqlite3_r
2ffe0 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e  eset()],.** then
2fff0 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72   the call will r
30000 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  eturn [SQLITE_MI
30010 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73  SUSE].  If any s
30020 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a  qlite3_bind_().*
30030 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73  * routine is pas
30040 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20  sed a [prepared 
30050 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
30060 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
30070 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  ed, the.** resul
30080 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  t is undefined a
30090 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d  nd probably harm
300a0 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64  ful..**.** ^Bind
300b0 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65  ings are not cle
300c0 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ared by the [sql
300d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f  ite3_reset()] ro
300e0 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75  utine..** ^Unbou
300f0 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  nd parameters ar
30100 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
30110 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
30120 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
30130 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
30140 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
30150 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a  success or an.**
30160 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
30170 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77   anything goes w
30180 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  rong..** ^[SQLIT
30190 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20  E_TOOBIG] might 
301a0 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  be returned if t
301b0 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72  he size of a str
301c0 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65  ing or BLOB.** e
301d0 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d  xceeds limits im
301e0 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  posed by [sqlite
301f0 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
30200 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20  _LIMIT_LENGTH]) 
30210 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41  or.** [SQLITE_MA
30220 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b  X_LENGTH]..** ^[
30230 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73  SQLITE_RANGE] is
30240 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
30250 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e   parameter.** in
30260 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
30270 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e  nge.  ^[SQLITE_N
30280 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65  OMEM] is returne
30290 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61  d if malloc() fa
302a0 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ils..**.** See a
302b0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
302c0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
302d0 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nt()],.** [sqlit
302e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
302f0 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b  r_name()], and [
30300 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
30310 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
30320 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
30330 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65  bind_blob(sqlite
30340 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
30350 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e  nst void*, int n
30360 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
30370 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
30380 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74  ind_blob64(sqlit
30390 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
303a0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69  onst void*, sqli
303b0 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20  te3_uint64,.    
303c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
303d0 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64      void(*)(void
303e0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
303f0 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c  _bind_double(sql
30400 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
30410 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71   double);.int sq
30420 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
30430 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30440 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  t, int);.int sql
30450 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28  ite3_bind_int64(
30460 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30470 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  nt, sqlite3_int6
30480 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  4);.int sqlite3_
30490 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  bind_null(sqlite
304a0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69  3_stmt*, int);.i
304b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
304c0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
304d0 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  t*,int,const cha
304e0 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  r*,int,void(*)(v
304f0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
30500 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
30510 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30520 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
30530 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
30540 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
30550 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73  e3_bind_text64(s
30560 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30570 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  t, const char*, 
30580 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a  sqlite3_uint64,.
30590 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
305a0 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29           void(*)
305b0 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65  (void*), unsigne
305c0 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29  d char encoding)
305d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
305e0 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  nd_value(sqlite3
305f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
30600 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
30610 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
30620 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 73 71 6c  bind_pointer(sql
30630 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
30640 20 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68   void*, const ch
30650 61 72 2a 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  ar*,void(*)(void
30660 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
30670 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
30680 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30690 74 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73  t, int n);.int s
306a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
306b0 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73  blob64(sqlite3_s
306c0 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
306d0 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a  e3_uint64);../*.
306e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
306f0 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
30700 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  eters.** METHOD:
30710 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
30720 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
30730 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
30740 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
30750 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74   of [SQL paramet
30760 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72  ers].** in a [pr
30770 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30780 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ].  SQL paramete
30790 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66  rs are tokens of
307a0 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22   the.** form "?"
307b0 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22  , "?NNN", ":AAA"
307c0 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41  , "$AAA", or "@A
307d0 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61  AA" that serve a
307e0 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72  s.** placeholder
307f0 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61  s for values tha
30800 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62  t are [sqlite3_b
30810 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64  ind_blob | bound
30820 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61  ].** to the para
30830 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65  meters at a late
30840 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  r time..**.** ^(
30850 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74  This routine act
30860 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
30870 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c  e index of the l
30880 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73  argest (rightmos
30890 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  t).** parameter.
308a0 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
308b0 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
308c0 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
308d0 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   to the.** numbe
308e0 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61  r of unique para
308f0 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
30900 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
30910 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64  NN form are used
30920 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62  ,.** there may b
30930 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
30940 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  st.)^.**.** See 
30950 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
30960 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
30970 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
30980 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
30990 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
309a0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
309b0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
309c0 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
309d0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
309e0 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
309f0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
30a00 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
30a10 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
30a20 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  eter.** METHOD: 
30a30 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
30a40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30a50 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
30a60 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61  ame(P,N) interfa
30a70 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  ce returns.** th
30a80 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d  e name of the N-
30a90 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  th [SQL paramete
30aa0 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  r] in the [prepa
30ab0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
30ac0 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d  ..** ^(SQL param
30ad0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
30ae0 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  m "?NNN" or ":AA
30af0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
30b00 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61  "$AAA".** have a
30b10 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74   name which is t
30b20 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22  he string "?NNN"
30b30 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
30b40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
30b50 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  * respectively..
30b60 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
30b70 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22  s, the initial "
30b80 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22  :" or "$" or "@"
30b90 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e   or "?".** is in
30ba0 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f  cluded as part o
30bb0 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a  f the name.)^.**
30bc0 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20   ^Parameters of 
30bd0 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74  the form "?" wit
30be0 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67  hout a following
30bf0 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f   integer have no
30c00 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65   name.** and are
30c10 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20   referred to as 
30c20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61  "nameless" or "a
30c30 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
30c40 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ers"..**.** ^The
30c50 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61   first host para
30c60 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
30c70 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a  ex of 1, not 0..
30c80 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61  **.** ^If the va
30c90 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20  lue N is out of 
30ca0 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
30cb0 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  N-th parameter i
30cc0 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
30cd0 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
30ce0 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  rned.  ^The retu
30cf0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a  rned string is.*
30d00 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d  * always in UTF-
30d10 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20  8 encoding even 
30d20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72  if the named par
30d30 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72  ameter was.** or
30d40 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
30d50 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
30d60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
30d70 31 36 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  16()],.** [sqlit
30d80 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
30d90 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
30da0 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e  prepare16_v3()].
30db0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
30dc0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
30dd0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
30de0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
30df0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
30e00 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
30e10 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
30e20 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
30e30 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
30e40 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
30e50 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
30e60 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30e70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30e80 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
30e90 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
30ea0 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45  Given Name.** ME
30eb0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
30ec0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  mt.**.** ^Return
30ed0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
30ee0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67   SQL parameter g
30ef0 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
30f00 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61  ^The.** index va
30f10 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
30f20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65  suitable for use
30f30 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
30f40 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  * parameter to [
30f50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
30f60 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
30f70 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69  ].  ^A zero.** i
30f80 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f  s returned if no
30f90 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65   matching parame
30fa0 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e  ter is found.  ^
30fb0 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
30fc0 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
30fd0 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
30fe0 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
30ff0 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
31000 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
31010 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
31020 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
31030 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 0a 2a  are16_v2()] or.*
31040 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
31050 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v3()]..**.*
31060 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
31070 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
31080 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
31090 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
310a0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
310b0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
310c0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
310d0 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a  ter_name()]..*/.
310e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
310f0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
31100 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31110 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
31120 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
31130 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
31140 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
31150 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
31160 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
31170 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43  e3_stmt.**.** ^C
31180 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
31190 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
311a0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
311b0 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73  ()] does not res
311c0 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  et.** the [sqlit
311d0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
311e0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70  indings] on a [p
311f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31200 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73  t]..** ^Use this
31210 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65   routine to rese
31220 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
31230 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
31240 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
31250 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  ear_bindings(sql
31260 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
31270 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
31280 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20  mber Of Columns 
31290 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
312a0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
312b0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52  e3_stmt.**.** ^R
312c0 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
312d0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
312e0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
312f0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
31300 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31310 6d 65 6e 74 5d 2e 20 5e 49 66 20 74 68 69 73 20  ment]. ^If this 
31320 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
31330 30 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  0, that means th
31340 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  e .** [prepared 
31350 73 74 61 74 65 6d 65 6e 74 5d 20 72 65 74 75 72  statement] retur
31360 6e 73 20 6e 6f 20 64 61 74 61 20 28 66 6f 72 20  ns no data (for 
31370 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41  example an [UPDA
31380 54 45 5d 29 2e 0a 2a 2a 20 5e 48 6f 77 65 76 65  TE])..** ^Howeve
31390 72 2c 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  r, just because 
313a0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
313b0 75 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20  urns a positive 
313c0 6e 75 6d 62 65 72 20 64 6f 65 73 20 6e 6f 74 0a  number does not.
313d0 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 6f 6e 65  ** mean that one
313e0 20 6f 72 20 6d 6f 72 65 20 72 6f 77 73 20 6f 66   or more rows of
313f0 20 64 61 74 61 20 77 69 6c 6c 20 62 65 20 72 65   data will be re
31400 74 75 72 6e 65 64 2e 20 20 5e 41 20 53 45 4c 45  turned.  ^A SELE
31410 43 54 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  CT statement.** 
31420 77 69 6c 6c 20 61 6c 77 61 79 73 20 68 61 76 65  will always have
31430 20 61 20 70 6f 73 69 74 69 76 65 20 73 71 6c 69   a positive sqli
31440 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
31450 28 29 20 62 75 74 20 64 65 70 65 6e 64 69 6e 67  () but depending
31460 20 6f 6e 20 74 68 65 0a 2a 2a 20 57 48 45 52 45   on the.** WHERE
31470 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69   clause constrai
31480 6e 74 73 20 61 6e 64 20 74 68 65 20 74 61 62 6c  nts and the tabl
31490 65 20 63 6f 6e 74 65 6e 74 2c 20 69 74 20 6d 69  e content, it mi
314a0 67 68 74 20 72 65 74 75 72 6e 20 6e 6f 20 72 6f  ght return no ro
314b0 77 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ws..**.** See al
314c0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  so: [sqlite3_dat
314d0 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  a_count()].*/.in
314e0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
314f0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
31500 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
31510 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
31520 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
31530 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45  Result Set.** ME
31540 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
31550 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  mt.**.** ^These 
31560 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
31570 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
31580 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61  d to a particula
31590 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74  r column.** in t
315a0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
315b0 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
315c0 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c  ement.  ^The sql
315d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
315e0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
315f0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
31600 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
31610 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
31620 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  ing.** and sqlit
31630 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
31640 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
31650 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
31660 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
31670 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
31680 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
31690 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72  r is the [prepar
316a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
316b0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
316c0 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
316d0 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65  atement. ^The se
316e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
316f0 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  s the.** column 
31700 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65  number.  ^The le
31710 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  ftmost column is
31720 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
31730 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
31740 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
31750 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
31760 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  her the [prepare
31770 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
31780 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
31790 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
317a0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
317b0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
317c0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
317d0 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
317e0 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
317f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
31800 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
31810 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
31820 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  l the next call 
31830 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
31840 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73  lumn_name() or s
31850 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
31860 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61  me16() on the sa
31870 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
31880 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
31890 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69  loc() fails duri
318a0 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e  ng the processin
318b0 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74  g of either rout
318c0 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d  ine.** (for exam
318d0 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e  ple during a con
318e0 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46  version from UTF
318f0 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68  -8 to UTF-16) th
31900 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  en a.** NULL poi
31910 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
31920 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
31930 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
31940 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75  lumn is the valu
31950 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c  e of the "AS" cl
31960 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74  ause for.** that
31970 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72   column, if ther
31980 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73  e is an AS claus
31990 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  e.  If there is 
319a0 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20  no AS clause.** 
319b0 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  then the name of
319c0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75   the column is u
319d0 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d  nspecified and m
319e0 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a  ay change from.*
319f0 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66  * one release of
31a00 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e   SQLite to the n
31a10 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ext..*/.const ch
31a20 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
31a30 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  mn_name(sqlite3_
31a40 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63  stmt*, int N);.c
31a50 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
31a60 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
31a70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31a80 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int N);../*.** C
31a90 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20  API3REF: Source 
31aa0 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65  Of Data In A Que
31ab0 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54  ry Result.** MET
31ac0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
31ad0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
31ae0 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
31af0 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
31b00 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73  mine the databas
31b10 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a  e, table, and.**
31b20 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
31b30 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e  at is the origin
31b40 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72   of a particular
31b50 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
31b60 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74  n.** [SELECT] st
31b70 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  atement..** ^The
31b80 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
31b90 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
31ba0 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
31bb0 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
31bc0 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72  ither a UTF-8 or
31bd0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
31be0 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f   ^The _database_
31bf0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
31c00 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
31c10 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
31c20 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
31c30 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
31c40 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
31c50 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
31c60 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
31c70 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72   name..** ^The r
31c80 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
31c90 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
31ca0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
31cb0 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
31cc0 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
31cd0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
31ce0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
31cf0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
31d00 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
31d10 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
31d20 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
31d30 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
31d40 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
31d50 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
31d60 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
31d70 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
31d80 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
31d90 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
31da0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
31db0 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
31dc0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
31dd0 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
31de0 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
31df0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
31e00 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
31e10 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
31e20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
31e30 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
31e40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
31e50 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
31e60 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
31e70 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
31e80 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
31e90 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
31ea0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
31eb0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
31ec0 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
31ed0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
31ee0 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
31ef0 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
31f00 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
31f10 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
31f20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
31f30 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
31f40 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
31f50 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
31f60 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
31f70 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
31f80 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
31f90 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
31fa0 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
31fb0 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
31fc0 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
31fd0 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
31fe0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
31ff0 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
32000 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
32010 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
32020 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
32030 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
32040 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
32050 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
32060 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
32070 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
32080 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
32090 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
320a0 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
320b0 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
320c0 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
320d0 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
320e0 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
320f0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
32100 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
32110 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
32120 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
32130 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
32140 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
32150 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
32160 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
32170 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
32180 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
32190 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
321a0 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
321b0 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
321c0 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
321d0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
321e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
321f0 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
32200 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
32210 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
32220 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
32230 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
32240 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
32250 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
32260 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
32270 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
32280 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
32290 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
322a0 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
322b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
322c0 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
322d0 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
322e0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
322f0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
32300 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
32310 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
32320 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
32330 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
32340 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
32350 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
32360 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
32370 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
32380 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
32390 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
323a0 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
323b0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
323c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
323d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
323e0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
323f0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
32400 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
32410 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
32420 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
32430 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
32440 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
32450 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
32460 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
32470 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
32480 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
32490 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
324a0 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48  y Result.** METH
324b0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
324c0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72  .**.** ^(The fir
324d0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
324e0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
324f0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68  ement]..** If th
32500 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  is statement is 
32510 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
32520 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68  ment and the Nth
32530 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a   column of the.*
32540 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c  * returned resul
32550 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53  t set of that [S
32560 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c  ELECT] is a tabl
32570 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e  e column (not an
32580 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
32590 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e  r subquery) then
325a0 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
325b0 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a  pe of the table.
325c0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74  ** column is ret
325d0 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68  urned.)^  ^If th
325e0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
325f0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69  the result set i
32600 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  s an.** expressi
32610 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20  on or subquery, 
32620 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  then a NULL poin
32630 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
32640 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
32650 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61  d string is alwa
32660 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  ys UTF-8 encoded
32670 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  ..**.** ^(For ex
32680 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65  ample, given the
32690 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
326a0 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54  :.**.** CREATE T
326b0 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41  ABLE t1(c1 VARIA
326c0 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74  NT);.**.** and t
326d0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61  he following sta
326e0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
326f0 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c  piled:.**.** SEL
32700 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46  ECT c1 + 1, c1 F
32710 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68  ROM t1;.**.** th
32720 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64  is routine would
32730 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69   return the stri
32740 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72  ng "VARIANT" for
32750 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75   the second resu
32760 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d  lt.** column (i=
32770 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20  =1), and a NULL 
32780 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20  pointer for the 
32790 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c  first result col
327a0 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a  umn (i==0).)^.**
327b0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
327c0 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d   dynamic run-tim
327d0 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a  e typing.  ^So j
327e0 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f  ust because a co
327f0 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61  lumn.** is decla
32800 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61  red to contain a
32810 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65   particular type
32820 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74   does not mean t
32830 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20  hat the.** data 
32840 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63  stored in that c
32850 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20  olumn is of the 
32860 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20  declared type.  
32870 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72  SQLite is.** str
32880 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74  ongly typed, but
32890 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64   the typing is d
328a0 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69  ynamic not stati
328b0 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20  c.  ^Type.** is 
328c0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
328d0 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65  individual value
328e0 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20  s, not with the 
328f0 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73  containers.** us
32900 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65  ed to hold those
32910 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73   values..*/.cons
32920 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
32930 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
32940 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
32950 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
32960 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
32970 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65  ecltype16(sqlite
32980 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
32990 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
329a0 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53  valuate An SQL S
329b0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48  tatement.** METH
329c0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
329d0 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
329e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
329f0 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
32a00 70 61 72 65 64 20 75 73 69 6e 67 20 61 6e 79 20  pared using any 
32a10 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  of.** [sqlite3_p
32a20 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
32a30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
32a40 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70  3()], [sqlite3_p
32a50 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 0a  repare16_v2()],.
32a60 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  ** or [sqlite3_p
32a70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20 6f  repare16_v3()] o
32a80 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67  r one of the leg
32a90 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
32aa0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
32ab0 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
32ac0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
32ad0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
32ae0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
32af0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
32b00 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
32b10 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  e statement..**.
32b20 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
32b30 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
32b40 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  f the sqlite3_st
32b50 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
32b60 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
32b70 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
32b80 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
32b90 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
32ba0 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  vX" interfaces.*
32bb0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
32bc0 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v3()], [sqlit
32bd0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
32be0 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
32bf0 72 65 31 36 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b  re16_v3()],.** [
32c00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
32c10 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f  6_v2()] or the o
32c20 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69  lder legacy.** i
32c30 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
32c40 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
32c50 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
32c60 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
32c70 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
32c80 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 20 69  "vX" interface i
32c90 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
32ca0 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
32cb0 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
32cc0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
32cd0 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
32ce0 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
32cf0 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61  .** ^In the lega
32d00 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
32d10 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
32d20 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
32d30 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20  QLITE_BUSY],.** 
32d40 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
32d50 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
32d60 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
32d70 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
32d80 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76  .** ^With the "v
32d90 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
32da0 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
32db0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
32dc0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
32dd0 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
32de0 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
32df0 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   well..**.** ^[S
32e00 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
32e10 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
32e20 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
32e30 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
32e40 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
32e50 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
32e60 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
32e70 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
32e80 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a  t is a [COMMIT].
32e90 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
32ea0 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
32eb0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
32ec0 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
32ed0 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
32ee0 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
32ef0 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
32f00 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63   [COMMIT] and oc
32f10 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a  curs within an.*
32f20 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
32f30 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
32f40 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
32f50 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
32f60 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
32f70 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  uing..**.** ^[SQ
32f80 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
32f90 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
32fa0 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
32fb0 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
32fc0 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
32fd0 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
32fe0 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
32ff0 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
33000 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
33010 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
33020 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
33030 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
33040 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
33050 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
33060 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
33070 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ate..**.** ^If t
33080 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
33090 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
330a0 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
330b0 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
330c0 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
330d0 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
330e0 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
330f0 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
33100 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
33110 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
33120 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
33130 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
33140 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
33150 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
33160 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
33170 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
33180 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
33190 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
331a0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ** ^[SQLITE_ERRO
331b0 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
331c0 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
331d0 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
331e0 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
331f0 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
33200 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
33210 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
33220 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
33230 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
33240 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
33250 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
33260 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
33270 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  sg()]..** ^With 
33280 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
33290 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
332a0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
332b0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
332c0 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
332d0 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
332e0 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
332f0 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
33300 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
33310 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
33320 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
33330 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
33340 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
33350 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20  ment].  ^In the 
33360 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
33370 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
33380 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
33390 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
333a0 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
333b0 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
333c0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
333d0 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
333e0 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
333f0 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
33400 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
33410 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
33420 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
33430 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
33440 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
33450 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
33460 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
33470 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
33480 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
33490 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
334a0 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
334b0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
334c0 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
334d0 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
334e0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
334f0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
33500 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
33510 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
33520 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
33530 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
33540 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73  .** For all vers
33550 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75  ions of SQLite u
33560 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69  p to and includi
33570 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63  ng 3.6.23.1, a c
33580 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
33590 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20  e3_reset()] was 
335a0 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73  required after s
335b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65  qlite3_step() re
335c0 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a  turned anything.
335d0 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ** other than [S
335e0 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72  QLITE_ROW] befor
335f0 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  e any subsequent
33600 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
33610 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
33620 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65  .  Failure to re
33630 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
33640 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
33650 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65   .** [sqlite3_re
33660 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73  set()] would res
33670 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  ult in an [SQLIT
33680 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e  E_MISUSE] return
33690 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
336a0 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66  _step().  But af
336b0 74 65 72 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36  ter [version 3.6
336c0 2e 32 33 2e 31 5d 20 28 5b 64 61 74 65 6f 66 3a  .23.1] ([dateof:
336d0 33 2e 36 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71  3.6.23.1],.** sq
336e0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67  lite3_step() beg
336f0 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73  an.** calling [s
33700 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
33710 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
33720 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e   this circumstan
33730 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61  ce rather.** tha
33740 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  n returning [SQL
33750 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68  ITE_MISUSE].  Th
33760 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64  is is not consid
33770 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69  ered a compatibi
33780 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65  lity.** break be
33790 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63  cause any applic
337a0 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20  ation that ever 
337b0 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49  receives an SQLI
337c0 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a  TE_MISUSE error.
337d0 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20  ** is broken by 
337e0 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65  definition.  The
337f0 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
33800 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65  TORESET] compile
33810 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  -time option.** 
33820 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
33830 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63  estore the legac
33840 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  y behavior..**.*
33850 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
33860 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20  face Alert:</b> 
33870 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
33880 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c  terface, the sql
33890 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41  ite3_step().** A
338a0 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
338b0 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
338c0 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f  r code, [SQLITE_
338d0 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
338e0 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f  g any.** error o
338f0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
33900 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c  E_BUSY] and [SQL
33910 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
33920 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b  u must call.** [
33930 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
33940 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
33950 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
33960 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
33970 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
33980 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
33990 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
339a0 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
339b0 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
339c0 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
339d0 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
339e0 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
339f0 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
33a00 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
33a10 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
33a20 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
33a30 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
33a40 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
33a50 65 70 61 72 65 5f 76 33 28 29 5d 20 6f 72 20 5b  epare_v3()] or [
33a60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33a70 76 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  v2()].** or [sql
33a80 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
33a90 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
33aa0 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
33ab0 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
33ac0 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
33ad0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
33ae0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
33af0 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
33b00 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
33b10 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
33b20 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
33b30 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
33b40 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
33b50 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
33b60 20 6f 66 20 74 68 65 20 22 76 58 22 20 69 6e 74   of the "vX" int
33b70 65 72 66 61 63 65 73 20 69 73 20 72 65 63 6f 6d  erfaces is recom
33b80 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  mended..*/.int s
33b90 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
33ba0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
33bb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
33bc0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
33bd0 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a  n a result set.*
33be0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
33bf0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
33c00 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
33c10 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63  ount(P) interfac
33c20 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
33c30 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
33c40 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  in the.** curren
33c50 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
33c60 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70  ult set of [prep
33c70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
33c80 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72  P..** ^If prepar
33c90 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64  ed statement P d
33ca0 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73  oes not have res
33cb0 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65  ults ready to re
33cc0 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c  turn.** (via cal
33cd0 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ls to the [sqlit
33ce0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20  e3_column_int | 
33cf0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
33d00 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ()] of.** interf
33d10 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74  aces) then sqlit
33d20 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
33d30 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e   returns 0..** ^
33d40 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
33d50 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
33d60 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30  e also returns 0
33d70 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20   if P is a NULL 
33d80 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65  pointer..** ^The
33d90 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
33da0 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72  unt(P) routine r
33db0 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20  eturns 0 if the 
33dc0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
33dd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
33de0 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b  p](P) returned [
33df0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e  SQLITE_DONE].  ^
33e00 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
33e10 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c  _count(P).** wil
33e20 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72  l return non-zer
33e30 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61  o if previous ca
33e40 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
33e50 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
33e60 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  .** [SQLITE_ROW]
33e70 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20  , except in the 
33e80 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41  case of the [PRA
33e90 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f  GMA incremental_
33ea0 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65  vacuum].** where
33eb0 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
33ec0 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61  ns zero since ea
33ed0 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20  ch step of that 
33ee0 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72  multi-step.** pr
33ef0 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63  agma returns 0 c
33f00 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a  olumns of data..
33f10 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
33f20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
33f30 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
33f40 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
33f50 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
33f60 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
33f70 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
33f80 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a  ental Datatypes.
33f90 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
33fa0 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e  ITE_TEXT.**.** ^
33fb0 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20  (Every value in 
33fc0 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
33fd0 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
33fe0 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
33ff0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
34000 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
34010 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
34020 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
34030 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
34040 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
34050 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
34060 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
34070 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  l>)^.**.** These
34080 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63   constants are c
34090 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66  odes for each of
340a0 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a   those types..**
340b0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
340c0 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f  e SQLITE_TEXT co
340d0 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20  nstant was also 
340e0 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  used in SQLite v
340f0 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20  ersion 2.** for 
34100 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66  a completely dif
34110 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20  ferent meaning. 
34120 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c   Software that l
34130 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74  inks against bot
34140 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  h.** SQLite vers
34150 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65  ion 2 and SQLite
34160 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c   version 3 shoul
34170 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45  d use SQLITE3_TE
34180 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54  XT, not.** SQLIT
34190 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69  E_TEXT..*/.#defi
341a0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  ne SQLITE_INTEGE
341b0 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  R  1.#define SQL
341c0 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23  ITE_FLOAT    2.#
341d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c  define SQLITE_BL
341e0 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65  OB     4.#define
341f0 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20   SQLITE_NULL    
34200 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45   5.#ifdef SQLITE
34210 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51  _TEXT.# undef SQ
34220 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a  LITE_TEXT.#else.
34230 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
34240 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69  TEXT     3.#endi
34250 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  f.#define SQLITE
34260 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a  3_TEXT     3../*
34270 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
34280 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d  sult Values From
34290 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57   A Query.** KEYW
342a0 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63  ORDS: {column ac
342b0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a  cess functions}.
342c0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
342d0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 3c 62  e3_stmt.**.** <b
342e0 3e 53 75 6d 6d 61 72 79 3a 3c 2f 62 3e 0a 2a 2a  >Summary:</b>.**
342f0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 74 61   <blockquote><ta
34300 62 6c 65 20 62 6f 72 64 65 72 3d 30 20 63 65 6c  ble border=0 cel
34310 6c 70 61 64 64 69 6e 67 3d 30 20 63 65 6c 6c 73  lpadding=0 cells
34320 70 61 63 69 6e 67 3d 30 3e 0a 2a 2a 20 3c 74 72  pacing=0>.** <tr
34330 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
34340 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 3c 2f 62 3e 3c  column_blob</b><
34350 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 42 4c 4f  td>&rarr;<td>BLO
34360 42 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e  B result.** <tr>
34370 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
34380 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 3c 2f 62 3e  olumn_double</b>
34390 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 52 45  <td>&rarr;<td>RE
343a0 41 4c 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72  AL result.** <tr
343b0 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
343c0 63 6f 6c 75 6d 6e 5f 69 6e 74 3c 2f 62 3e 3c 74  column_int</b><t
343d0 64 3e 26 72 61 72 72 3b 3c 74 64 3e 33 32 2d 62  d>&rarr;<td>32-b
343e0 69 74 20 49 4e 54 45 47 45 52 20 72 65 73 75 6c  it INTEGER resul
343f0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  t.** <tr><td><b>
34400 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
34410 6e 74 36 34 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  nt64</b><td>&rar
34420 72 3b 3c 74 64 3e 36 34 2d 62 69 74 20 49 4e 54  r;<td>64-bit INT
34430 45 47 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c  EGER result.** <
34440 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
34450 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 3c 2f 62  3_column_text</b
34460 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55  ><td>&rarr;<td>U
34470 54 46 2d 38 20 54 45 58 54 20 72 65 73 75 6c 74  TF-8 TEXT result
34480 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
34490 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
344a0 78 74 31 36 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  xt16</b><td>&rar
344b0 72 3b 3c 74 64 3e 55 54 46 2d 31 36 20 54 45 58  r;<td>UTF-16 TEX
344c0 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e  T result.** <tr>
344d0 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
344e0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 3c 2f 62 3e 3c  olumn_value</b><
344f0 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 54 68 65  td>&rarr;<td>The
34500 20 72 65 73 75 6c 74 20 61 73 20 61 6e 20 0a 2a   result as an .*
34510 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
34520 7c 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  |unprotected sql
34530 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
34540 63 74 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 26  ct..** <tr><td>&
34550 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 3c  nbsp;<td>&nbsp;<
34560 74 64 3e 26 6e 62 73 70 3b 0a 2a 2a 20 3c 74 72  td>&nbsp;.** <tr
34570 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
34580 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 3c 2f 62 3e  column_bytes</b>
34590 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 53 69  <td>&rarr;<td>Si
345a0 7a 65 20 6f 66 20 61 20 42 4c 4f 42 0a 2a 2a 20  ze of a BLOB.** 
345b0 6f 72 20 61 20 55 54 46 2d 38 20 54 45 58 54 20  or a UTF-8 TEXT 
345c0 72 65 73 75 6c 74 20 69 6e 20 62 79 74 65 73 0a  result in bytes.
345d0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
345e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
345f0 65 73 31 36 26 6e 62 73 70 3b 26 6e 62 73 70 3b  es16&nbsp;&nbsp;
34600 3c 2f 62 3e 0a 2a 2a 20 3c 74 64 3e 26 72 61 72  </b>.** <td>&rar
34610 72 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 74  r;&nbsp;&nbsp;<t
34620 64 3e 53 69 7a 65 20 6f 66 20 55 54 46 2d 31 36  d>Size of UTF-16
34630 0a 2a 2a 20 54 45 58 54 20 69 6e 20 62 79 74 65  .** TEXT in byte
34640 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  s.** <tr><td><b>
34650 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
34660 79 70 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  ype</b><td>&rarr
34670 3b 3c 74 64 3e 44 65 66 61 75 6c 74 0a 2a 2a 20  ;<td>Default.** 
34680 64 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20  datatype of the 
34690 72 65 73 75 6c 74 0a 2a 2a 20 3c 2f 74 61 62 6c  result.** </tabl
346a0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
346b0 2a 2a 0a 2a 2a 20 3c 62 3e 44 65 74 61 69 6c 73  **.** <b>Details
346c0 3a 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  :</b>.**.** ^The
346d0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
346e0 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
346f0 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f  bout a single co
34700 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72  lumn of the curr
34710 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  ent.** result ro
34720 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e  w of a query.  ^
34730 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68  In every case th
34740 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
34750 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
34760 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
34770 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
34780 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75  t is being evalu
34790 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  ated (the [sqlit
347a0 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61  e3_stmt*].** tha
347b0 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
347c0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  rom [sqlite3_pre
347d0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
347e0 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
347f0 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65  s).** and the se
34800 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
34810 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
34820 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
34830 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ch information.*
34840 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
34850 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d  rned. ^The leftm
34860 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
34870 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73  e result set has
34880 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a   the index 0..**
34890 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
348a0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
348b0 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74  esult can be det
348c0 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  ermined using.**
348d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
348e0 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _count()]..**.**
348f0 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
34900 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
34910 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
34920 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
34930 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
34940 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
34950 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
34960 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
34970 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
34980 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
34990 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
349a0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
349b0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
349c0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
349d0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
349e0 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
349f0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
34a00 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
34a10 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
34a20 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
34a30 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
34a40 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
34a50 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
34a60 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
34a70 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
34a80 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
34a90 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
34aa0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
34ab0 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
34ac0 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
34ad0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
34ae0 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
34af0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
34b00 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
34b10 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
34b20 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
34b30 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
34b40 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
34b50 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
34b60 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
34b70 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
34b80 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
34b90 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
34ba0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
34bb0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ed..**.** The fi
34bc0 72 73 74 20 73 69 78 20 69 6e 74 65 72 66 61 63  rst six interfac
34bd0 65 73 20 28 5f 62 6c 6f 62 2c 20 5f 64 6f 75 62  es (_blob, _doub
34be0 6c 65 2c 20 5f 69 6e 74 2c 20 5f 69 6e 74 36 34  le, _int, _int64
34bf0 2c 20 5f 74 65 78 74 2c 20 61 6e 64 20 5f 74 65  , _text, and _te
34c00 78 74 31 36 29 0a 2a 2a 20 65 61 63 68 20 72 65  xt16).** each re
34c10 74 75 72 6e 20 74 68 65 20 76 61 6c 75 65 20 6f  turn the value o
34c20 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  f a result colum
34c30 6e 20 69 6e 20 61 20 73 70 65 63 69 66 69 63 20  n in a specific 
34c40 64 61 74 61 20 66 6f 72 6d 61 74 2e 20 20 49 66  data format.  If
34c50 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 20 63  .** the result c
34c60 6f 6c 75 6d 6e 20 69 73 20 6e 6f 74 20 69 6e 69  olumn is not ini
34c70 74 69 61 6c 6c 79 20 69 6e 20 74 68 65 20 72 65  tially in the re
34c80 71 75 65 73 74 65 64 20 66 6f 72 6d 61 74 20 28  quested format (
34c90 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  for example,.** 
34ca0 69 66 20 74 68 65 20 71 75 65 72 79 20 72 65 74  if the query ret
34cb0 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
34cc0 62 75 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  but the sqlite3_
34cd0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 6e  column_text() in
34ce0 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 75 73  terface.** is us
34cf0 65 64 20 74 6f 20 65 78 74 72 61 63 74 20 74 68  ed to extract th
34d00 65 20 76 61 6c 75 65 29 20 74 68 65 6e 20 61 6e  e value) then an
34d10 20 61 75 74 6f 6d 61 74 69 63 20 74 79 70 65 20   automatic type 
34d20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65  conversion is pe
34d30 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  rformed..**.** ^
34d40 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
34d50 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e  mn_type() routin
34d60 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
34d70 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
34d80 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65   | datatype code
34d90 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61  ] for the initia
34da0 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f  l data type.** o
34db0 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  f the result col
34dc0 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72  umn.  ^The retur
34dd0 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
34de0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
34df0 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
34e00 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
34e10 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
34e20 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
34e30 45 5f 4e 55 4c 4c 5d 2e 0a 2a 2a 20 54 68 65 20  E_NULL]..** The 
34e40 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
34e50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
34e60 79 70 65 28 29 20 63 61 6e 20 62 65 20 75 73 65  ype() can be use
34e70 64 20 74 6f 20 64 65 63 69 64 65 20 77 68 69 63  d to decide whic
34e80 68 0a 2a 2a 20 6f 66 20 74 68 65 20 66 69 72 73  h.** of the firs
34e90 74 20 73 69 78 20 69 6e 74 65 72 66 61 63 65 20  t six interface 
34ea0 73 68 6f 75 6c 64 20 62 65 20 75 73 65 64 20 74  should be used t
34eb0 6f 20 65 78 74 72 61 63 74 20 74 68 65 20 63 6f  o extract the co
34ec0 6c 75 6d 6e 20 76 61 6c 75 65 2e 0a 2a 2a 20 54  lumn value..** T
34ed0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
34ee0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
34ef0 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
34f00 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
34f10 20 6e 6f 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   no.** automatic
34f20 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
34f30 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
34f40 66 6f 72 20 74 68 65 20 76 61 6c 75 65 20 69 6e  for the value in
34f50 20 71 75 65 73 74 69 6f 6e 2e 20 20 0a 2a 2a 20   question.  .** 
34f60 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e  After a type con
34f70 76 65 72 73 69 6f 6e 2c 20 74 68 65 20 72 65 73  version, the res
34f80 75 6c 74 20 6f 66 20 63 61 6c 6c 69 6e 67 20 73  ult of calling s
34f90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
34fa0 70 65 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65 66  pe().** is undef
34fb0 69 6e 65 64 2c 20 74 68 6f 75 67 68 20 68 61 72  ined, though har
34fc0 6d 6c 65 73 73 2e 20 20 46 75 74 75 72 65 0a 2a  mless.  Future.*
34fd0 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
34fe0 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
34ff0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
35000 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
35010 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
35020 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
35030 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  sion..**.** If t
35040 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
35050 4c 4f 42 20 6f 72 20 61 20 54 45 58 54 20 73 74  LOB or a TEXT st
35060 72 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 73  ring, then the s
35070 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
35080 74 65 73 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  tes().** or sqli
35090 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
350a0 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  16() interfaces 
350b0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
350c0 65 74 65 72 6d 69 6e 65 20 74 68 65 20 73 69 7a  etermine the siz
350d0 65 0a 2a 2a 20 6f 66 20 74 68 61 74 20 42 4c 4f  e.** of that BLO
350e0 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  B or string..**.
350f0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
35100 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
35110 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
35120 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
35130 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72  umn_bytes().** r
35140 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
35150 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
35160 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
35170 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
35180 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
35190 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
351a0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
351b0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
351c0 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
351d0 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
351e0 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
351f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
35200 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
35210 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
35220 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
35230 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35240 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
35250 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
35260 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
35270 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
35280 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  8 string and ret
35290 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
352a0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
352b0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
352c0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
352d0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
352e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
352f0 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
35300 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
35310 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
35320 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
35330 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
35340 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
35350 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
35360 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
35370 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
35380 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
35390 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
353a0 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73  ult is a UTF-8 s
353b0 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
353c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
353d0 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  16() converts.**
353e0 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
353f0 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72  TF-16 and then r
35400 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
35410 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
35420 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
35430 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
35440 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
35450 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75  lumn_bytes16() u
35460 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
35470 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
35480 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
35490 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74  e to a UTF-16 st
354a0 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
354b0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
354c0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
354d0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
354e0 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
354f0 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
35500 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
35510 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
35520 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73  *.** ^The values
35530 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
35540 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
35550 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73  es()] and .** [s
35560 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
35570 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20  tes16()] do not 
35580 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f  include the zero
35590 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20   terminators at 
355a0 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
355b0 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20  e string.  ^For 
355c0 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
355d0 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ues returned by.
355e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
355f0 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
35600 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
35610 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74  bytes16()] are t
35620 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
35630 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
35640 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
35650 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
35660 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67  s..**.** ^String
35670 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
35680 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
35690 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
356a0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
356b0 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
356c0 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
356d0 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
356e0 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
356f0 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
35700 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
35710 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
35720 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61  length BLOB is a
35730 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
35740 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a  *.** <b>Warning:
35750 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74  </b> ^The object
35760 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
35770 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
35780 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b  ue()] is an.** [
35790 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
357a0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
357b0 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69 74 68  t.  In a multith
357c0 72 65 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65  readed environme
357d0 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74  nt,.** an unprot
357e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
357f0 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f  lue object may o
35800 6e 6c 79 20 62 65 20 75 73 65 64 20 73 61 66 65  nly be used safe
35810 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ly with.** [sqli
35820 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
35830 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
35840 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a  esult_value()]..
35850 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f  ** If the [unpro
35860 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
35870 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74  alue] object ret
35880 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
35890 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
358a0 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20  e()] is used in 
358b0 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69  any other way, i
358c0 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a  ncluding calls.*
358d0 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  * to routines li
358e0 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ke [sqlite3_valu
358f0 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74  e_int()], [sqlit
35900 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
35910 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
35920 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
35930 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
35940 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
35950 0a 2a 2a 20 48 65 6e 63 65 2c 20 74 68 65 20 73  .** Hence, the s
35960 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
35970 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 0a  lue() interface.
35980 2a 2a 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f  ** is normally o
35990 6e 6c 79 20 75 73 65 66 75 6c 20 77 69 74 68 69  nly useful withi
359a0 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  n the implementa
359b0 74 69 6f 6e 20 6f 66 20 0a 2a 2a 20 5b 61 70 70  tion of .** [app
359c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
359d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
359e0 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  or [virtual tabl
359f0 65 73 5d 2c 20 6e 6f 74 20 77 69 74 68 69 6e 0a  es], not within.
35a00 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 61 70 70  ** top-level app
35a10 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 2e 0a 2a  lication code..*
35a20 2a 0a 2a 2a 20 54 68 65 20 74 68 65 73 65 20 72  *.** The these r
35a30 6f 75 74 69 6e 65 73 20 6d 61 79 20 61 74 74 65  outines may atte
35a40 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
35a50 68 65 20 64 61 74 61 74 79 70 65 20 6f 66 20 74  he datatype of t
35a60 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 46  he result..** ^F
35a70 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  or example, if t
35a80 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
35a90 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c  esentation is FL
35aa0 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72  OAT and a text r
35ab0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75  esult.** is requ
35ac0 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f  ested, [sqlite3_
35ad0 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75  snprintf()] is u
35ae0 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
35af0 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a  o perform the.**
35b00 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f   conversion auto
35b10 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68  matically.  ^(Th
35b20 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c  e following tabl
35b30 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f  e details the co
35b40 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61  nversions.** tha
35b50 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a  t are applied:.*
35b60 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
35b70 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
35b80 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
35b90 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e  th> Internal<br>
35ba0 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73  Type <th> Reques
35bb0 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  ted<br>Type <th>
35bc0 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a    Conversion.**.
35bd0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
35be0 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  L    <td> INTEGE
35bf0 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20  R   <td> Result 
35c00 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  is 0.** <tr><td>
35c10 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
35c20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65  FLOAT    <td> Re
35c30 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c  sult is 0.0.** <
35c40 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
35c50 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
35c60 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61  <td> Result is a
35c70 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
35c80 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
35c90 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
35ca0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
35cb0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
35cc0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
35cd0 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  GER  <td>  FLOAT
35ce0 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
35cf0 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f   from integer to
35d00 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
35d10 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
35d20 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
35d30 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
35d40 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a  of the integer.*
35d50 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
35d60 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  ER  <td>   BLOB 
35d70 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
35d80 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a  INTEGER->TEXT.**
35d90 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
35da0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
35db0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
35dc0 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
35dd0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
35de0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
35df0 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
35e00 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a  g of the float.*
35e10 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
35e20 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  T   <td>   BLOB 
35e30 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
35e40 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74  o BLOB.** <tr><t
35e50 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
35e60 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
35e70 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
35e80 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  R.** <tr><td>  T
35e90 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  EXT    <td>  FLO
35ea0 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  AT    <td> [CAST
35eb0 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72  ] to REAL.** <tr
35ec0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
35ed0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
35ee0 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
35ef0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
35f00 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
35f10 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
35f20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
35f30 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
35f40 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
35f50 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a   [CAST] to REAL.
35f60 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
35f70 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  B    <td>   TEXT
35f80 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a      <td> Add a z
35f90 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
35fa0 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61  f needed.** </ta
35fb0 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
35fc0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f  uote>)^.**.** No
35fd0 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
35fe0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
35ff0 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
36000 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
36010 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
36020 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
36030 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
36040 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
36050 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
36060 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
36070 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
36080 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
36090 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
360a0 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
360b0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
360c0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
360d0 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
360e0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
360f0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
36100 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
36110 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
36120 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
36130 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
36140 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
36150 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
36160 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
36170 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
36180 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
36190 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
361a0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
361b0 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
361c0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
361d0 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
361e0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
361f0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
36200 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
36210 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
36220 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
36230 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
36240 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
36250 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
36260 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
36270 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
36280 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
36290 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
362a0 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
362b0 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
362c0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
362d0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
362e0 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
362f0 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
36300 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
36310 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
36320 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
36330 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
36340 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
36350 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
36360 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
36370 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
36380 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
36390 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
363a0 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65  r pointer refere
363b0 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62  nces will have b
363c0 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
363d0 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
363e0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
363f0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
36400 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
36410 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
36420 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
36430 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
36440 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
36450 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
36460 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
36470 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 70 6f  ** The safest po
36480 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
36490 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
364a0 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
364b0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
364c0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
364d0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
364e0 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f  umn_text() follo
364f0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
36500 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
36510 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
36520 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
36530 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
36540 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
36550 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
36560 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
36570 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65  text16() followe
36580 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
36590 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c  umn_bytes16()</l
365a0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
365b0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
365c0 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
365d0 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
365e0 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69  _text(),.** sqli
365f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
36600 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ), or sqlite3_co
36610 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
36620 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
36630 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20   result.** into 
36640 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d  the desired form
36650 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
36660 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36670 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  ytes() or.** sql
36680 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
36690 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68  s16() to find th
366a0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
366b0 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
366c0 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71  x calls.** to sq
366d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
366e0 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  t() or sqlite3_c
366f0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
36700 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  h calls to.** sq
36710 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
36720 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e  es16(), and do n
36730 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ot mix calls to 
36740 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
36750 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20  ext16().** with 
36760 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
36770 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
36780 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e  .**.** ^The poin
36790 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
367a0 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
367b0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
367c0 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
367d0 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
367e0 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
367f0 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
36800 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
36810 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
36820 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
36830 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  d.  ^The memory 
36840 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
36850 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
36860 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
36870 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
36880 20 44 6f 20 6e 6f 74 20 70 61 73 73 20 74 68 65   Do not pass the
36890 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
368a0 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
368b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
368c0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
368d0 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
368e0 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  . into.** [sqlit
368f0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
36900 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20  * ^(If a memory 
36910 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
36920 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
36930 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
36940 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
36950 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
36960 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
36970 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
36980 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
36990 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
369a0 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
369b0 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
369c0 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
369d0 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
369e0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
369f0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
36a00 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
36a10 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
36a20 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  M].)^.*/.const v
36a30 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
36a40 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
36a50 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
36a60 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
36a70 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
36a80 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
36a90 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
36aa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
36ab0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
36ac0 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
36ad0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
36ae0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
36af0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
36b00 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e   iCol);.const un
36b10 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
36b20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
36b30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
36b40 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
36b50 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
36b60 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
36b70 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
36b80 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76  iCol);.sqlite3_v
36b90 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f  alue *sqlite3_co
36ba0 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74  lumn_value(sqlit
36bb0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
36bc0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
36bd0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
36be0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
36bf0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
36c00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
36c10 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
36c20 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
36c30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36c40 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
36c50 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
36c60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36c70 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
36c80 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
36c90 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ect.** DESTRUCTO
36ca0 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  R: sqlite3_stmt.
36cb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36cc0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
36cd0 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
36ce0 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72   to delete a [pr
36cf0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
36d00 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  ]..** ^If the mo
36d10 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
36d20 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
36d30 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65  ement encountere
36d40 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f  d no errors.** o
36d50 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  r if the stateme
36d60 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e  nt is never been
36d70 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e   evaluated, then
36d80 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
36d90 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53  e() returns.** S
36da0 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74  QLITE_OK.  ^If t
36db0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
36dc0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61  valuation of sta
36dd0 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c  tement S failed,
36de0 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
36df0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74  _finalize(S) ret
36e00 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72  urns the appropr
36e10 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
36e20 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
36e30 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a  d error code]..*
36e40 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36e50 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f  3_finalize(S) ro
36e60 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
36e70 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
36e80 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c   during.** the l
36e90 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72  ife cycle of [pr
36ea0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
36eb0 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73  ] S:.** before s
36ec0 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76  tatement S is ev
36ed0 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66  er evaluated, af
36ee0 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f  ter.** one or mo
36ef0 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  re calls to [sql
36f00 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f  ite3_reset()], o
36f10 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c  r after any call
36f20 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
36f30 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65  step()] regardle
36f40 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
36f50 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65   not the stateme
36f60 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65  nt has.** comple
36f70 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a  ted execution..*
36f80 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73  *.** ^Invoking s
36f90 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
36fa0 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) on a NULL poin
36fb0 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ter is a harmles
36fc0 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54  s no-op..**.** T
36fd0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
36fe0 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65  ust finalize eve
36ff0 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ry [prepared sta
37000 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72  tement] in order
37010 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73   to avoid.** res
37020 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74  ource leaks.  It
37030 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65   is a grievous e
37040 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  rror for the app
37050 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20  lication to try 
37060 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70  to use.** a prep
37070 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
37080 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
37090 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79   finalized.  Any
370a0 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72   use of a prepar
370b0 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
370c0 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
370d0 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20  n finalized can 
370e0 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
370f0 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73  ned and.** undes
37100 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20  irable behavior 
37110 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74  such as segfault
37120 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75  s and heap corru
37130 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ption..*/.int sq
37140 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73  lite3_finalize(s
37150 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
37160 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
37170 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72  3REF: Reset A Pr
37180 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
37190 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f   Object.** METHO
371a0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
371b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
371c0 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69  3_reset() functi
371d0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
371e0 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65  reset a [prepare
371f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
37200 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69  object back to i
37210 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
37220 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65  , ready to be re
37230 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41  -executed..** ^A
37240 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
37250 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20   variables that 
37260 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64  had values bound
37270 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a   to them using.*
37280 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
37290 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
372a0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d  e3_bind_*() API]
372b0 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61   retain their va
372c0 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71  lues..** Use [sq
372d0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
372e0 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74  ings()] to reset
372f0 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a   the bindings..*
37300 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
37310 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
37320 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68  erface resets th
37330 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
37340 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b  ement] S.** back
37350 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   to the beginnin
37360 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d  g of its program
37370 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
37380 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
37390 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
373a0 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
373b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
373c0 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
373d0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
373e0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a   [SQLITE_DONE],.
373f0 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65  ** or if [sqlite
37400 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e  3_step(S)] has n
37410 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e  ever before been
37420 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a   called on S,.**
37430 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
37440 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
37450 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
37460 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
37470 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
37480 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
37490 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
374a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
374b0 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
374c0 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
374d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
374e0 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  )] returns an ap
374f0 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
37500 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
37510 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
37520 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
37530 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
37540 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66  the values.** of
37550 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69   any [sqlite3_bi
37560 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73  nd_blob|bindings
37570 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] on the [prepar
37580 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
37590 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
375a0 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
375b0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
375c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
375d0 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
375e0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  SQL Functions.**
375f0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
37600 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
37610 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f  utines}.** KEYWO
37620 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
37630 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
37640 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f  nction}.** KEYWO
37650 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
37660 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
37670 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48  nctions}.** METH
37680 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
37690 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
376a0 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79  ns (collectively
376b0 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74   known as "funct
376c0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
376d0 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75  tines").** are u
376e0 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66  sed to add SQL f
376f0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
37700 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64  egates or to red
37710 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69  efine the behavi
37720 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e  or.** of existin
37730 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  g SQL functions 
37740 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  or aggregates.  
37750 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65  The only differe
37760 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20  nces between.** 
37770 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
37780 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f  re the text enco
37790 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f  ding expected fo
377a0 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  r.** the second 
377b0 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e  parameter (the n
377c0 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ame of the funct
377d0 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65  ion being create
377e0 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72  d).** and the pr
377f0 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63  esence or absenc
37800 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f  e of a destructo
37810 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a  r callback for.*
37820 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
37830 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a  n data pointer..
37840 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
37850 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
37860 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
37870 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68  ection] to which
37880 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63   the SQL.** func
37890 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64  tion is to be ad
378a0 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70  ded.  ^If an app
378b0 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f  lication uses mo
378c0 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61  re than one data
378d0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
378e0 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74  on then applicat
378f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
37900 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62  functions must b
37910 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61  e added.** to ea
37920 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
37930 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c  ection separatel
37940 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  y..**.** ^The se
37950 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
37960 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
37970 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
37980 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a  o be created or.
37990 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e  ** redefined.  ^
379a0 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
379b0 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
379c0 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69  d to 255 bytes i
379d0 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70  n a UTF-8.** rep
379e0 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63  resentation, exc
379f0 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65  lusive of the ze
37a00 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro-terminator.  
37a10 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e  ^Note that the n
37a20 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69  ame.** length li
37a30 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20  mit is in UTF-8 
37a40 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61  bytes, not chara
37a50 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36  cters nor UTF-16
37a60 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e   bytes.  .** ^An
37a70 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65  y attempt to cre
37a80 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  ate a function w
37a90 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d  ith a longer nam
37aa0 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74  e.** will result
37ab0 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   in [SQLITE_MISU
37ac0 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e  SE] being return
37ad0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  ed..**.** ^The t
37ae0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28  hird parameter (
37af0 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20  nArg).** is the 
37b00 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
37b10 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c  nts that the SQL
37b20 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
37b30 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e  aggregate takes.
37b40 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65   ^If this parame
37b50 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ter is -1, then 
37b60 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
37b70 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
37b80 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75   may take any nu
37b90 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
37ba0 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  s between 0 and 
37bb0 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74  the limit.** set
37bc0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
37bd0 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
37be0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29  T_FUNCTION_ARG])
37bf0 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a  .  If the third.
37c00 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ** parameter is 
37c10 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20  less than -1 or 
37c20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37  greater than 127
37c30 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
37c40 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e  or is.** undefin
37c50 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
37c60 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c  ourth parameter,
37c70 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69   eTextRep, speci
37c80 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51  fies what.** [SQ
37c90 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74  LITE_UTF8 | text
37ca0 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20   encoding] this 
37cb0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65  SQL function pre
37cc0 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20  fers for.** its 
37cd0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65  parameters.  The
37ce0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
37cf0 75 6c 64 20 73 65 74 20 74 68 69 73 20 70 61 72  uld set this par
37d00 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51  ameter to.** [SQ
37d10 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66  LITE_UTF16LE] if
37d20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d   the function im
37d30 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76  plementation inv
37d40 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  okes .** [sqlite
37d50 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
37d60 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c  ()] on an input,
37d70 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
37d80 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69  6BE] if the.** i
37d90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
37da0 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76  vokes [sqlite3_v
37db0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d  alue_text16be()]
37dc0 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72   on an input, or
37dd0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
37de0 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76  6] if [sqlite3_v
37df0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69  alue_text16()] i
37e00 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49  s used, or [SQLI
37e10 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65  TE_UTF8].** othe
37e20 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d  rwise.  ^The sam
37e30 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d  e SQL function m
37e40 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
37e50 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
37e60 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65  using.** differe
37e70 6e 74 20 70 72 65 66 65 72 72 65 64 20 74 65 78  nt preferred tex
37e80 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74  t encodings, wit
37e90 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c  h different impl
37ea0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a  ementations for.
37eb0 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67  ** each encoding
37ec0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69  ..** ^When multi
37ed0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
37ee0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
37ef0 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
37f00 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
37f10 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
37f20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
37f30 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
37f40 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
37f50 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rsion..**.** ^Th
37f60 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
37f70 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c  er may optionall
37f80 79 20 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b  y be ORed with [
37f90 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
37fa0 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e  STIC].** to sign
37fb0 61 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e 63  al that the func
37fc0 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73  tion will always
37fd0 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
37fe0 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a   result given.**
37ff0 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73   the same inputs
38000 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65   within a single
38010 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
38020 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69   Most SQL functi
38030 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72  ons are.** deter
38040 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62  ministic.  The b
38050 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28  uilt-in [random(
38060 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  )] SQL function 
38070 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  is an example of
38080 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74   a.** function t
38090 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72  hat is not deter
380a0 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53  ministic.  The S
380b0 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e  QLite query plan
380c0 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a  ner is able to.*
380d0 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69  * perform additi
380e0 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f  onal optimizatio
380f0 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73  ns on determinis
38100 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73  tic functions, s
38110 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20  o use.** of the 
38120 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e  [SQLITE_DETERMIN
38130 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72  ISTIC] flag is r
38140 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65  ecommended where
38150 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a   possible..**.**
38160 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72   ^(The fifth par
38170 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
38180 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
38190 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
381a0 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75  ion of the.** fu
381b0 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
381c0 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
381d0 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71  ointer using [sq
381e0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
381f0 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  )].)^.**.** ^The
38200 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20   sixth, seventh 
38210 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d  and eighth param
38220 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
38230 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
38240 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
38250 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
38260 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
38270 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
38280 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
38290 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c  gregate. ^A scal
382a0 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
382b0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
382c0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
382d0 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
382e0 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70  ack only; NULL p
382f0 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20  ointers must be 
38300 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53  passed as the xS
38310 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a  tep and xFinal.*
38320 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41  * parameters. ^A
38330 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
38340 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
38350 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
38360 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20  ion of xStep.** 
38370 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
38380 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74  ULL pointer must
38390 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78   be passed for x
383a0 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65  Func. ^To delete
383b0 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20   an existing.** 
383c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  SQL function or 
383d0 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20  aggregate, pass 
383e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f  NULL pointers fo
383f0 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
38400 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
38410 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  s..**.** ^(If th
38420 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  e ninth paramete
38430 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
38440 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
38450 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a  ) is not NULL,.*
38460 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73  * then it is des
38470 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20  tructor for the 
38480 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
38490 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68   pointer. .** Th
384a0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
384b0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
384c0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
384d0 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20  eted, either by 
384e0 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61  being.** overloa
384f0 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20  ded or when the 
38500 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
38510 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a  ion closes.)^.**
38520 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
38530 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64   is also invoked
38540 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a   if the call to.
38550 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
38560 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
38570 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20  fails..** ^When 
38580 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63  the destructor c
38590 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74  allback of the t
385a0 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  enth parameter i
385b0 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a  s invoked, it.**
385c0 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e   is passed a sin
385d0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
385e0 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ch is a copy of 
385f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
38600 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72  data .** pointer
38610 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66   which was the f
38620 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  ifth parameter t
38630 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
38640 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a  _function_v2()..
38650 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72  **.** ^It is per
38660 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
38670 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
38680 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
38690 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
386a0 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
386b0 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
386c0 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
386d0 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
386e0 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
386f0 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
38700 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
38710 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75    ^SQLite will u
38720 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
38730 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f  entation that mo
38740 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
38750 65 73 20 74 68 65 20 77 6