/ Hex Artifact Content
Login

Artifact e9e275be6c05a3d5a3e6107c72c4fd8b0aaa6573b65e414373964ecd047fb19f:


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 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
5180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
5190: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (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 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
51c0: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
51d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (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 57 52 49 54 45 20  ITE_IOERR_WRITE 
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 33 3c 3c  ITE_IOERR | (3<<
5220: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5230: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
5240: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<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 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
5280: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<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 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
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 36 3c 3c 38 29 29  _IOERR | (6<<8))
52e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52f0: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
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 37 3c 3c 38 29 29 0a  IOERR | (7<<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 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
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 38 3c 3c 38 29 29 0a 23  OERR | (8<<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 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
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 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<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 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
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 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
53e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53f0: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
5400: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5410: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
5420: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5430: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
5440: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5450: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
5460: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5470: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
5480: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5490: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
54a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
54b0: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
54c0: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
54d0: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
54e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
54f0: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
5500: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5510: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
5520: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5530: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
5540: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5550: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
5560: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5570: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
5580: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5590: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
55a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
55b0: 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20  RR_SHMOPEN      
55c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
55d0: 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64  RR | (18<<8)).#d
55e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
55f0: 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20  RR_SHMSIZE      
5600: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5610: 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64  RR | (19<<8)).#d
5620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5630: 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20  RR_SHMLOCK      
5640: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5650: 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64  RR | (20<<8)).#d
5660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5670: 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20  RR_SHMMAP       
5680: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5690: 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64  RR | (21<<8)).#d
56a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
56b0: 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20  RR_SEEK         
56c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
56d0: 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64  RR | (22<<8)).#d
56e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
56f0: 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20  RR_DELETE_NOENT 
5700: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5710: 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64  RR | (23<<8)).#d
5720: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5730: 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20  RR_MMAP         
5740: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5750: 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64  RR | (24<<8)).#d
5760: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5770: 52 52 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20  RR_GETTEMPPATH  
5780: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5790: 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64  RR | (25<<8)).#d
57a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
57b0: 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  RR_CONVPATH     
57c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
57d0: 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64  RR | (26<<8)).#d
57e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
57f0: 52 52 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20  RR_VNODE        
5800: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5810: 52 52 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64  RR | (27<<8)).#d
5820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5830: 52 52 5f 41 55 54 48 20 20 20 20 20 20 20 20 20  RR_AUTH         
5840: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5850: 52 52 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64  RR | (28<<8)).#d
5860: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5870: 52 52 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20  RR_BEGIN_ATOMIC 
5880: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5890: 52 52 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64  RR | (29<<8)).#d
58a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
58b0: 52 52 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43  RR_COMMIT_ATOMIC
58c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
58d0: 52 52 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64  RR | (30<<8)).#d
58e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
58f0: 52 52 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  RR_ROLLBACK_ATOM
5900: 49 43 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45  IC   (SQLITE_IOE
5910: 52 52 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64  RR | (31<<8)).#d
5920: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
5930: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
5940: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
5950: 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  KED |  (1<<8)).#
5960: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5970: 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  SY_RECOVERY     
5980: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5990: 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a  SY   |  (1<<8)).
59a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
59b0: 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20  USY_SNAPSHOT    
59c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
59d0: 55 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29  USY   |  (2<<8))
59e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59f0: 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44  CANTOPEN_NOTEMPD
5a00: 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  IR      (SQLITE_
5a10: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38  CANTOPEN | (1<<8
5a20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a30: 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52  E_CANTOPEN_ISDIR
5a40: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5a50: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c  E_CANTOPEN | (2<
5a60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a70: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c  ITE_CANTOPEN_FUL
5a80: 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  LPATH       (SQL
5a90: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5aa0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5ab0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43  QLITE_CANTOPEN_C
5ac0: 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53  ONVPATH       (S
5ad0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5ae0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5af0: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5b00: 5f 44 49 52 54 59 57 41 4c 20 20 20 20 20 20 20  _DIRTYWAL       
5b10: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5b20: 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69   | (5<<8)).#defi
5b30: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
5b40: 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 20  T_VTAB          
5b50: 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50    (SQLITE_CORRUP
5b60: 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  T | (1<<8)).#def
5b70: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5b80: 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20  NLY_RECOVERY    
5b90: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5ba0: 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  NLY | (1<<8)).#d
5bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5bc0: 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20  DONLY_CANTLOCK  
5bd0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5be0: 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a  DONLY | (2<<8)).
5bf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5c00: 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b  EADONLY_ROLLBACK
5c10: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5c20: 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29  EADONLY | (3<<8)
5c30: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5c40: 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45  _READONLY_DBMOVE
5c50: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  D        (SQLITE
5c60: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c  _READONLY | (4<<
5c70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5c80: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
5c90: 49 4e 49 54 20 20 20 20 20 20 20 28 53 51 4c 49  INIT       (SQLI
5ca0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35  TE_READONLY | (5
5cb0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5cc0: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
5cd0: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
5ce0: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
5cf0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5d00: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5d10: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  HECK        (SQL
5d20: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5d30: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5d40: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5d50: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20  NT_COMMITHOOK   
5d60: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5d70: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  NT | (2<<8)).#de
5d80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5d90: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45  TRAINT_FOREIGNKE
5da0: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5db0: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29  TRAINT | (3<<8))
5dc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5dd0: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54  CONSTRAINT_FUNCT
5de0: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ION     (SQLITE_
5df0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c  CONSTRAINT | (4<
5e00: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5e10: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e  ITE_CONSTRAINT_N
5e20: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c  OTNULL      (SQL
5e30: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5e40: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5e50: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5e60: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20  NT_PRIMARYKEY   
5e70: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5e80: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  NT | (6<<8)).#de
5e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5ea0: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20  TRAINT_TRIGGER  
5eb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5ec0: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29  TRAINT | (7<<8))
5ed0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ee0: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55  CONSTRAINT_UNIQU
5ef0: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  E       (SQLITE_
5f00: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c  CONSTRAINT | (8<
5f10: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5f20: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56  ITE_CONSTRAINT_V
5f30: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAB         (SQL
5f40: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5f50: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
5f60: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5f70: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20  NT_ROWID        
5f80: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5f90: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65  NT |(10<<8)).#de
5fa0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5fb0: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
5fc0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
5fd0: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
5fe0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5ff0: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
6000: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
6010: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
6020: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
6030: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
6040: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
6050: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ING | (1<<8)).#d
6060: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
6070: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20  H_USER          
6080: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54       (SQLITE_AUT
6090: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  H | (1<<8)).#def
60a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f  ine SQLITE_OK_LO
60b0: 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20  AD_PERMANENTLY  
60c0: 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20     (SQLITE_OK | 
60d0: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
60e0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
60f0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
6100: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
6110: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
6120: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
6130: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
6140: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
6150: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
6160: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
6170: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
6180: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
6190: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
61a0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
61b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
61c0: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
61d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
61e0: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
61f0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6200: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6210: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
6220: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6230: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
6240: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6250: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6260: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
6270: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6280: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
6290: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
62a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
62b0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
62c0: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
62d0: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
62e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
62f0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
6300: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6310: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
6320: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6330: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
6340: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6350: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
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 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
6380: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6390: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
63a0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
63b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
63c0: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
63d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
63e0: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
63f0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6400: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6410: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
6420: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
6430: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6440: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6450: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
6460: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
6470: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6490: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
64a0: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
64b0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
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 4a 4f 55 52  E_OPEN_MAIN_JOUR
64e0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
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 4a 4f 55 52  E_OPEN_TEMP_JOUR
6520: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
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 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
6560: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
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 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
65a0: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
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 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
65e0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
65f0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6600: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6610: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6620: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
6630: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
6640: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6650: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6660: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6670: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
6680: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
6690: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
66a0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
66b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
66c0: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
66d0: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
66e0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
66f0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6700: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6710: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
6720: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
6730: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6740: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
6750: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6760: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
6770: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
6780: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
6790: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
67a0: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
67b0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
67c0: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
67d0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
67e0: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
67f0: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
6800: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
6810: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
6820: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
6830: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
6840: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
6850: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
6860: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
6870: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
6880: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
6890: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
68a0: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
68b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
68c0: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
68d0: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
68e0: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
68f0: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
6900: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6910: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
6920: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
6930: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
6940: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
6950: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
6960: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
6970: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
6980: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
6990: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
69a0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
69b0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
69c0: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
69d0: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
69e0: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
69f0: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
6a00: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
6a10: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
6a20: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
6a30: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
6a40: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
6a50: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
6a60: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
6a70: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6a80: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
6a90: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
6aa0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
6ab0: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
6ac0: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
6ad0: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
6ae0: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
6af0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6b00: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
6b10: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
6b20: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
6b30: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
6b40: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
6b50: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
6b60: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
6b70: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
6b80: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
6b90: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
6ba0: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
6bb0: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
6bc0: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
6bd0: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
6be0: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
6bf0: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
6c00: 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51  changed.  The SQ
6c10: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
6c20: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
6c30: 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74  .** flag indicat
6c40: 65 73 20 74 68 61 74 20 61 20 66 69 6c 65 20 63  es that a file c
6c50: 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64  annot be deleted
6c60: 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65   when open.  The
6c70: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  .** SQLITE_IOCAP
6c80: 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20  _IMMUTABLE flag 
6c90: 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
6ca0: 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a  he file is on.**
6cb0: 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61   read-only media
6cc0: 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63   and cannot be c
6cd0: 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70  hanged even by p
6ce0: 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a  rocesses with.**
6cf0: 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c   elevated privil
6d00: 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eges..**.** The 
6d10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54  SQLITE_IOCAP_BAT
6d20: 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  CH_ATOMIC proper
6d30: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ty means that th
6d40: 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20  e underlying.** 
6d50: 66 69 6c 65 73 79 73 74 65 6d 20 73 75 70 70 6f  filesystem suppo
6d60: 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69 70  rts doing multip
6d70: 6c 65 20 77 72 69 74 65 20 6f 70 65 72 61 74 69  le write operati
6d80: 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20 77  ons atomically w
6d90: 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72 69  hen those.** wri
6da0: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  te operations ar
6db0: 65 20 62 72 61 63 6b 65 74 65 64 20 62 79 20 5b  e bracketed by [
6dc0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
6dd0: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
6de0: 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   and.** [SQLITE_
6df0: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
6e00: 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a 23  MIC_WRITE]..*/.#
6e10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6e20: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
6e30: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6e40: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
6e50: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6e60: 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20  C512            
6e70: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
6e80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6e90: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
6ea0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6eb0: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
6ec0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
6ed0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
6ee0: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
6ef0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6f00: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
6f10: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
6f20: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6f30: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20  _IOCAP_ATOMIC8K 
6f40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6f50: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65  00000020.#define
6f60: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6f70: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20  OMIC16K         
6f80: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
6f90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6fa0: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
6fb0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6fc0: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
6fd0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6fe0: 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20  IC64K           
6ff0: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
7000: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
7010: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20  AP_SAFE_APPEND  
7020: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
7030: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
7040: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
7050: 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  TIAL            
7060: 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66   0x00000400.#def
7070: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
7080: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
7090: 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38  N_OPEN  0x000008
70a0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
70b0: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
70c0: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30  E_OVERWRITE    0
70d0: 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e  x00001000.#defin
70e0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49  e SQLITE_IOCAP_I
70f0: 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20 20  MMUTABLE        
7100: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
7110: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7120: 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d  IOCAP_BATCH_ATOM
7130: 49 43 20 20 20 20 20 20 20 20 20 20 20 30 78 30  IC           0x0
7140: 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0004000../*.** C
7150: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
7160: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
7170: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
7180: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
7190: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
71a0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
71b0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
71c0: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
71d0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
71e0: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
71f0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
7200: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
7210: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
7220: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
7230: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
7240: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
7250: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
7260: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
7270: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
7280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7290: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
72a0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
72b0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
72c0: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
72d0: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
72e0: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
72f0: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
7300: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
7310: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
7320: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
7330: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
7340: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
7350: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
7360: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
7370: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
7380: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
7390: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
73a0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
73b0: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
73c0: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
73d0: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
73e0: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
73f0: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
7400: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
7410: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
7420: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
7430: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
7440: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
7450: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
7460: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
7470: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
7480: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
7490: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
74a0: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
74b0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
74c0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
74d0: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
74e0: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
74f0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
7500: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
7510: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
7520: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
7530: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
7540: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
7550: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
7560: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
7570: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
7580: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
7590: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
75a0: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
75b0: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
75c0: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
75d0: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
75e0: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
75f0: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
7600: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
7610: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
7620: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
7630: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
7640: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
7650: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
7660: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
7670: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
7680: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
7690: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
76a0: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
76b0: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
76c0: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
76d0: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
76e0: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
76f0: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
7700: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
7710: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
7720: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
7730: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
7740: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
7750: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
7760: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
7770: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
7780: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
7790: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
77a0: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
77b0: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
77c0: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
77d0: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
77e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
77f0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
7800: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
7810: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
7820: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
7830: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
7840: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7850: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
7860: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
7870: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
7880: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
7890: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
78a0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
78b0: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
78c0: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
78d0: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
78e0: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
78f0: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
7900: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
7910: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
7920: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
7930: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
7940: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
7950: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
7960: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
7970: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
7980: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
7990: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
79a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
79b0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
79c0: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
79d0: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
79e0: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
79f0: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
7a00: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
7a10: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
7a20: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
7a30: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
7a40: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
7a50: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
7a60: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
7a70: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
7a80: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
7a90: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
7aa0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7ab0: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
7ac0: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
7ad0: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
7ae0: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
7af0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7b00: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
7b10: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
7b20: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7b30: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
7b40: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
7b50: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
7b60: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7b70: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
7b80: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
7b90: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
7ba0: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
7bb0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
7bc0: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
7bd0: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
7be0: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
7bf0: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
7c00: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
7c10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
7c20: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
7c30: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
7c40: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7c50: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
7c60: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7c70: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
7c80: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
7c90: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
7ca0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7cb0: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
7cc0: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
7cd0: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
7ce0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7cf0: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
7d00: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
7d10: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
7d20: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
7d30: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
7d40: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
7d50: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
7d60: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
7d70: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7d80: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
7d90: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7da0: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
7db0: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
7dc0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7dd0: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
7de0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
7df0: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
7e00: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
7e10: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
7e20: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
7e30: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
7e40: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
7e50: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
7e60: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
7e70: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
7e80: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
7e90: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
7ea0: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
7eb0: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
7ec0: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
7ed0: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
7ee0: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
7ef0: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
7f00: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
7f10: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
7f20: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
7f30: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
7f40: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7f50: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
7f60: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
7f70: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
7f80: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
7f90: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
7fa0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
7fb0: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
7fc0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
7fd0: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
7fe0: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
7ff0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
8000: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
8010: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
8020: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
8030: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
8040: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
8050: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
8060: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
8070: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
8080: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
8090: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
80a0: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
80b0: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
80c0: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
80d0: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
80e0: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
80f0: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
8100: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
8110: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
8120: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
8130: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
8140: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
8150: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
8160: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
8170: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
8180: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
8190: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
81a0: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
81b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
81c0: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
81d0: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
81e0: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
81f0: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
8200: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
8210: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
8220: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
8230: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
8240: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
8250: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
8260: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
8270: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
8280: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
8290: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
82a0: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
82b0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
82c0: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
82d0: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
82e0: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
82f0: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
8300: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
8310: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
8320: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
8330: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
8340: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
8350: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
8360: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
8370: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
8380: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
8390: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
83a0: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
83b0: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
83c0: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
83d0: 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A [file control 
83e0: 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f  opcodes | list o
83f0: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
8400: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
8410: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
8420: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
8430: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
8440: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
8450: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
8460: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
8470: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
8480: 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20  conflicts.  VFS 
8490: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
84a0: 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
84b0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
84c0: 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74  D] for file cont
84d0: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74  rol opcodes that
84e0: 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
84f0: 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a  recognize..**.**
8500: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
8510: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
8520: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
8530: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
8540: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
8550: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
8560: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
8570: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
8580: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
8590: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
85a0: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
85b0: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
85c0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
85d0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
85e0: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
85f0: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
8600: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
8610: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
8620: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
8630: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
8640: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
8650: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8660: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8670: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
8680: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
8690: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
86a0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
86b0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
86c0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
86d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
86e0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
86f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
8700: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8710: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
8720: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
8730: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8740: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
8750: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8760: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
8770: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8780: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
8790: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
87a0: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c  EQUENTIAL].** <l
87b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
87c0: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
87d0: 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20  N_OPEN].** <li> 
87e0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f  [SQLITE_IOCAP_PO
87f0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
8800: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
8810: 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
8820: 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  LE].** <li> [SQL
8830: 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f  ITE_IOCAP_BATCH_
8840: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ATOMIC].** </ul>
8850: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
8860: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
8870: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
8880: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
8890: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
88a0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
88b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
88c0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
88d0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
88e0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
88f0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
8900: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
8910: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
8920: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
8930: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
8940: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
8950: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8960: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
8970: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
8980: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
8990: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
89a0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
89b0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
89c0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
89d0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
89e0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
89f0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
8a00: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
8a10: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8a20: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
8a30: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8a40: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
8a50: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
8a60: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
8a70: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
8a80: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
8a90: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
8aa0: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
8ab0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
8ac0: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
8ad0: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
8ae0: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
8af0: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
8b00: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
8b10: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
8b20: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
8b30: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
8b40: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
8b50: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
8b60: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
8b70: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
8b80: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
8b90: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
8ba0: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
8bb0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
8bc0: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
8bd0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
8be0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
8bf0: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
8c00: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
8c10: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
8c20: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8c30: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
8c40: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
8c50: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
8c60: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8c70: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
8c80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
8c90: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
8ca0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
8cb0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
8cc0: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
8cd0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
8ce0: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
8cf0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
8d00: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8d10: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
8d20: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
8d30: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8d40: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
8d50: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
8d60: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8d70: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
8d80: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
8d90: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
8da0: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
8db0: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
8dc0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
8dd0: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
8de0: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
8df0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8e00: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
8e10: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
8e20: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
8e30: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8e40: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
8e50: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
8e60: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74  file*);.  /* Met
8e70: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
8e80: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
8e90: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53   1 */.  int (*xS
8ea0: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  hmMap)(sqlite3_f
8eb0: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69  ile*, int iPg, i
8ec0: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f  nt pgsz, int, vo
8ed0: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a  id volatile**);.
8ee0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b    int (*xShmLock
8ef0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8f00: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74   int offset, int
8f10: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a   n, int flags);.
8f20: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72    void (*xShmBar
8f30: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69  rier)(sqlite3_fi
8f40: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  le*);.  int (*xS
8f50: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33  hmUnmap)(sqlite3
8f60: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65  _file*, int dele
8f70: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65  teFlag);.  /* Me
8f80: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8f90: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8fa0: 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 2 */.  int (*x
8fb0: 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66  Fetch)(sqlite3_f
8fc0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8fd0: 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69  t64 iOfst, int i
8fe0: 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b  Amt, void **pp);
8ff0: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63  .  int (*xUnfetc
9000: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
9010: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
9020: 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b  iOfst, void *p);
9030: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
9040: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
9050: 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20  r version 3 */. 
9060: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d   /* Additional m
9070: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64  ethods may be ad
9080: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
9090: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  leases */.};../*
90a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
90b0: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74  andard File Cont
90c0: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b  rol Opcodes.** K
90d0: 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63  EYWORDS: {file c
90e0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20  ontrol opcodes} 
90f0: 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  {file control op
9100: 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  code}.**.** Thes
9110: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
9120: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
9130: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
9140: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
9150: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
9160: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
9170: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
9180: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9190: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
91a0: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ace..**.** <ul>.
91b0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
91c0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
91d0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
91e0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
91f0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9200: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
9210: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
9220: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
9230: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
9240: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
9250: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
9260: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
9270: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
9280: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
9290: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
92a0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
92b0: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
92c0: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
92d0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
92e0: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
92f0: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
9300: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
9310: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
9320: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
9330: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
9340: 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f  testing and is o
9350: 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68  nly available wh
9360: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  en the SQLITE_TE
9370: 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  ST.** compile-ti
9380: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  me option is use
9390: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
93a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
93b0: 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _HINT]].** The [
93c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
93d0: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
93e0: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
93f0: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
9400: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
9410: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
9420: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9430: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
9440: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
9450: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
9460: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
9470: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
9480: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
9490: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
94a0: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
94b0: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
94c0: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
94d0: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
94e0: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
94f0: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
9500: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
9510: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
9520: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
9530: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
9540: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9550: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
9560: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
9570: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
9580: 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  SIZE] opcode is 
9590: 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20  used to request 
95a0: 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20  that the VFS.** 
95b0: 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e  extends and trun
95c0: 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61  cates the databa
95d0: 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b  se file in chunk
95e0: 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63  s of a size spec
95f0: 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
9600: 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68  user. The fourth
9610: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
9620: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9630: 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a  ol()] should .**
9640: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74   point to an int
9650: 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20  eger (type int) 
9660: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
9670: 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f  ew chunk-size to
9680: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20   use.** for the 
9690: 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61  nominated databa
96a0: 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64  se. Allocating d
96b0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61  atabase file spa
96c0: 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63  ce in large.** c
96d0: 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61  hunks (say 1MB a
96e0: 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72  t a time), may r
96f0: 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65  educe file-syste
9700: 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20  m fragmentation 
9710: 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70  and.** improve p
9720: 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f  erformance on so
9730: 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a  me systems..**.*
9740: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9750: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
9760: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  R]].** The [SQLI
9770: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
9780: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73  INTER] opcode is
9790: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
97a0: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
97b0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
97c0: 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69  e] object associ
97d0: 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74  ated with a part
97e0: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
97f0: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
9800: 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45  See also [SQLITE
9810: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
9820: 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  OINTER]..**.** <
9830: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9840: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45  L_JOURNAL_POINTE
9850: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  R]].** The [SQLI
9860: 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c  TE_FCNTL_JOURNAL
9870: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
9880: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
9890: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
98a0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
98b0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
98c0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
98d0: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65   journal file (e
98e0: 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f  ither.** the [ro
98f0: 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20  llback journal] 
9900: 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68  or the [write-ah
9910: 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20  ead log]) for a 
9920: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
9930: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
9940: 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51  n.  See also [SQ
9950: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
9960: 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20  POINTER]..**.** 
9970: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9980: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d  TL_SYNC_OMITTED]
9990: 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69  ].** No longer i
99a0: 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  n use..**.** <li
99b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
99c0: 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SYNC]].** The [S
99d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
99e0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65  ] opcode is gene
99f0: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  rated internally
9a00: 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a   by SQLite and.*
9a10: 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46  * sent to the VF
9a20: 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65  S immediately be
9a30: 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d  fore the xSync m
9a40: 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
9a50: 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73   on a.** databas
9a60: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  e file descripto
9a70: 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53  r. Or, if the xS
9a80: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f  ync method is no
9a90: 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65  t invoked .** be
9aa0: 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68  cause the user h
9ab0: 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51  as configured SQ
9ac0: 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50  Lite with .** [P
9ad0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
9ae0: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
9af0: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69  ronous=OFF] it i
9b00: 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61  s invoked in pla
9b10: 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53  ce .** of the xS
9b20: 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d  ync method. In m
9b30: 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70  ost cases, the p
9b40: 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20  ointer argument 
9b50: 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74  passed with.** t
9b60: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
9b70: 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65   is NULL. Howeve
9b80: 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61  r, if the databa
9b90: 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67  se file is being
9ba0: 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61   synced.** as pa
9bb0: 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61  rt of a multi-da
9bc0: 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74  tabase commit, t
9bd0: 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  he argument poin
9be0: 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d  ts to a nul-term
9bf0: 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
9c00: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
9c10: 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73  transactions mas
9c20: 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  ter-journal file
9c30: 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61   name. VFSes tha
9c40: 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65  t .** do not nee
9c50: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68  d this signal sh
9c60: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
9c70: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
9c80: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a  . Applications .
9c90: 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ** should not ca
9ca0: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ll [sqlite3_file
9cb0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
9cc0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20   this opcode as 
9cd0: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a  doing so may .**
9ce0: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
9cf0: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
9d00: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
9d10: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
9d20: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  it.  .**.** <li>
9d30: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  [[SQLITE_FCNTL_C
9d40: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d  OMMIT_PHASETWO]]
9d50: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9d60: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
9d70: 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73  SETWO] opcode is
9d80: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
9d90: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a  nally by SQLite.
9da0: 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74  ** and sent to t
9db0: 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74  he VFS after a t
9dc0: 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62  ransaction has b
9dd0: 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d  een committed im
9de0: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74  mediately.** but
9df0: 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61   before the data
9e00: 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64  base is unlocked
9e10: 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  . VFSes that do 
9e20: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69  not need this si
9e30: 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73  gnal.** should s
9e40: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74  ilently ignore t
9e50: 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c  his opcode. Appl
9e60: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
9e70: 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  not call.** [sql
9e80: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9e90: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
9ea0: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
9eb0: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68  o may disrupt th
9ec0: 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  e .** operation 
9ed0: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
9ee0: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
9ef0: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
9f00: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9f10: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
9f20: 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65  _RETRY]].** ^The
9f30: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
9f40: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f  IN32_AV_RETRY] o
9f50: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9f60: 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d   configure autom
9f70: 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f  atic.** retry co
9f80: 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61  unts and interva
9f90: 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64  ls for certain d
9fa0: 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  isk I/O operatio
9fb0: 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69  ns for the.** wi
9fc0: 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f  ndows [VFS] in o
9fd0: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
9fe0: 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68  robustness in th
9ff0: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a  e presence of.**
a000: 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67   anti-virus prog
a010: 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c  rams.  By defaul
a020: 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56  t, the windows V
a030: 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69  FS will retry fi
a040: 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65  le read,.** file
a050: 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65   write, and file
a060: 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f   delete operatio
a070: 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65  ns up to 10 time
a080: 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a  s, with a delay.
a090: 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65  ** of 25 millise
a0a0: 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65  conds before the
a0b0: 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64   first retry and
a0c0: 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20   with the delay 
a0d0: 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79  increasing.** by
a0e0: 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32   an additional 2
a0f0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77  5 milliseconds w
a100: 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75  ith each subsequ
a110: 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73  ent retry.  This
a120: 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77  .** opcode allow
a130: 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75  s these two valu
a140: 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61  es (10 retries a
a150: 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  nd 25 millisecon
a160: 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20  ds of delay).** 
a170: 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20  to be adjusted. 
a180: 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20   The values are 
a190: 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20  changed for all 
a1a0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
a1b0: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74  ions.** within t
a1c0: 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e  he same process.
a1d0: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69    The argument i
a1e0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
a1f0: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a  n array of two.*
a200: 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65  * integers where
a210: 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67   the first integ
a220: 65 72 20 69 73 20 74 68 65 20 6e 65 77 20 72 65  er is the new re
a230: 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68  try count and th
a240: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65  e second.** inte
a250: 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79  ger is the delay
a260: 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74  .  If either int
a270: 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eger is negative
a280: 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69  , then the setti
a290: 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  ng.** is not cha
a2a0: 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64  nged but instead
a2b0: 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
a2c0: 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67   of that setting
a2d0: 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69   is written.** i
a2e0: 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e  nto the array en
a2f0: 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68  try, allowing th
a300: 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20  e current retry 
a310: 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a  settings to be.*
a320: 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20  * interrogated. 
a330: 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72   The zDbName par
a340: 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65  ameter is ignore
a350: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
a360: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
a370: 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68  IST_WAL]].** ^Th
a380: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a390: 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63  PERSIST_WAL] opc
a3a0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
a3b0: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
a3c0: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57  ** persistent [W
a3d0: 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64  AL | Write Ahead
a3e0: 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20   Log] setting.  
a3f0: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
a400: 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69  auxiliary.** wri
a410: 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64  te ahead log and
a420: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
a430: 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72  iles used for tr
a440: 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
a450: 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74  l.** are automat
a460: 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77  ically deleted w
a470: 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63  hen the latest c
a480: 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65  onnection to the
a490: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f   database.** clo
a4a0: 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65  ses.  Setting pe
a4b0: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
a4c0: 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66  e causes those f
a4d0: 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20  iles to persist 
a4e0: 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20  after.** close. 
a4f0: 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20   Persisting the 
a500: 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20  files is useful 
a510: 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65  when other proce
a520: 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  sses that do not
a530: 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70  .** have write p
a540: 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65  ermission on the
a550: 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61   directory conta
a560: 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  ining the databa
a570: 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20  se file want.** 
a580: 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61  to read the data
a590: 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68  base file, as th
a5a0: 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64  e WAL and shared
a5b0: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75   memory files mu
a5c0: 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f  st exist.** in o
a5d0: 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74  rder for the dat
a5e0: 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64  abase to be read
a5f0: 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74  able.  The fourt
a600: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
a610: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
a620: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74  control()] for t
a630: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c  his opcode shoul
a640: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  d be a pointer t
a650: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  o an integer..**
a660: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73   That integer is
a670: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65   0 to disable pe
a680: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
a690: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
a6a0: 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57   persistent.** W
a6b0: 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  AL mode.  If the
a6c0: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
a6d0: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
a6e0: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
a6f0: 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70  current.** WAL p
a700: 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69  ersistence setti
a710: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
a720: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
a730: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
a740: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a750: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a760: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70  FE_OVERWRITE] op
a770: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
a780: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
a790: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22  .** persistent "
a7a0: 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72  powersafe-overwr
a7b0: 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73  ite" or "PSOW" s
a7c0: 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f  etting.  The PSO
a7d0: 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74  W setting.** det
a7e0: 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c  ermines the [SQL
a7f0: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
a800: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62  AFE_OVERWRITE] b
a810: 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65  it of the.** xDe
a820: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
a830: 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65  ics methods. The
a840: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
a850: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
a860: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
a870: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
a880: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
a890: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
a8a0: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
a8b0: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
a8c0: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  ble zero-damage 
a8d0: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
a8e0: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a  ble zero-damage.
a8f0: 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ** mode.  If the
a900: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
a910: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
a920: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
a930: 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d  current.** zero-
a940: 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74  damage mode sett
a950: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
a960: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
a970: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
a980: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a990: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
a9a0: 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  e is invoked by 
a9b0: 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65  SQLite after ope
a9c0: 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20  ning.** a write 
a9d0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69  transaction to i
a9e0: 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e  ndicate that, un
a9f0: 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65  less it is rolle
aa00: 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a  d back for some.
aa10: 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65  ** reason, the e
aa20: 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66  ntire database f
aa30: 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72  ile will be over
aa40: 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63  written by the c
aa50: 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73  urrent .** trans
aa60: 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20  action. This is 
aa70: 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f  used by VACUUM o
aa80: 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
aa90: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
aaa0: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a  NTL_VFSNAME]].**
aab0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
aac0: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63  NTL_VFSNAME] opc
aad0: 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ode can be used 
aae0: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61  to obtain the na
aaf0: 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56  mes of.** all [V
ab00: 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53  FSes] in the VFS
ab10: 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d   stack.  The nam
ab20: 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46  es are of all VF
ab30: 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a  S shims and the.
ab40: 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d  ** final bottom-
ab50: 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72  level VFS are wr
ab60: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
ab70: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
ab80: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
ab90: 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72  loc()] and the r
aba0: 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20  esult is stored 
abb0: 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  in the char* var
abc0: 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68  iable.** that th
abd0: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
abe0: 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66  er of [sqlite3_f
abf0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70  ile_control()] p
ac00: 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65  oints to..** The
ac10: 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f   caller is respo
ac20: 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69  nsible for freei
ac30: 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68  ng the memory wh
ac40: 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74  en done.  As wit
ac50: 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f  h.** all file-co
ac60: 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74  ntrol actions, t
ac70: 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61  here is no guara
ac80: 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77  ntee that this w
ac90: 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  ill actually.** 
aca0: 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61  do anything.  Ca
acb0: 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69  llers should ini
acc0: 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72  tialize the char
acd0: 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20  * variable to a 
ace0: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
acf0: 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c  in case this fil
ad00: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74  e-control is not
ad10: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54   implemented.  T
ad20: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
ad30: 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20  .** is intended 
ad40: 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75  for diagnostic u
ad50: 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c  se only..**.** <
ad60: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ad70: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a  L_VFS_POINTER]].
ad80: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
ad90: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
ada0: 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20  R] opcode finds 
adb0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
adc0: 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56   top-level.** [V
add0: 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20  FSes] currently 
ade0: 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61  in use.  ^(The a
adf0: 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20  rgument X in.** 
ae00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
ae10: 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46  trol(db,SQLITE_F
ae20: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
ae30: 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f  ,X) must be.** o
ae40: 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33  f type "[sqlite3
ae50: 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73  _vfs] **".  This
ae60: 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65   opcodes will se
ae70: 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69  t *X.** to a poi
ae80: 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d  nter to the top-
ae90: 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20  level VFS.)^.** 
aea0: 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72 65 20  ^When there are 
aeb0: 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69  multiple VFS shi
aec0: 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c  ms in the stack,
aed0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e   this opcode fin
aee0: 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d  ds the.** upper-
aef0: 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a  most shim only..
af00: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
af10: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
af20: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61  ].** ^Whenever a
af30: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
af40: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61  ent is parsed, a
af50: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  n [SQLITE_FCNTL_
af60: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65  PRAGMA] .** file
af70: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74   control is sent
af80: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71   to the open [sq
af90: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
afa0: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ct corresponding
afb0: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62  .** to the datab
afc0: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63  ase file to whic
afd0: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61  h the pragma sta
afe0: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e  tement refers. ^
aff0: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  The argument.** 
b000: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  to the [SQLITE_F
b010: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
b020: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20  e control is an 
b030: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e  array of.** poin
b040: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
b050: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63  (char**) in whic
b060: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65  h the second ele
b070: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61  ment of the arra
b080: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  y.** is the name
b090: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61   of the pragma a
b0a0: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65  nd the third ele
b0b0: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75  ment is the argu
b0c0: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70  ment to the.** p
b0d0: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66  ragma or NULL if
b0e0: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20   the pragma has 
b0f0: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  no argument.  ^T
b100: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  he handler for a
b110: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  n.** [SQLITE_FCN
b120: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
b130: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69  control can opti
b140: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20  onally make the 
b150: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a  first element.**
b160: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61   of the char** a
b170: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f  rgument point to
b180: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e   a string obtain
b190: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
b1a0: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f  _mprintf()].** o
b1b0: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
b1c0: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67   and that string
b1d0: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
b1e0: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70   result of the p
b1f0: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20  ragma or.** the 
b200: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66  error message if
b210: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c   the pragma fail
b220: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  s. ^If the.** [S
b230: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b240: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
b250: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
b260: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e  _NOTFOUND], then
b270: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41   normal .** [PRA
b280: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20  GMA] processing 
b290: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20  continues.  ^If 
b2a0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
b2b0: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
b2c0: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
b2d0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
b2e0: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61  hen the parser a
b2f0: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
b300: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c  ** VFS has handl
b310: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74  ed the PRAGMA it
b320: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72  self and the par
b330: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20  ser generates a 
b340: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65  no-op.** prepare
b350: 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72  d statement if r
b360: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20  esult string is 
b370: 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65  NULL, or that re
b380: 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20  turns a copy.** 
b390: 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 74  of the result st
b3a0: 72 69 6e 67 20 69 66 20 74 68 65 20 73 74 72 69  ring if the stri
b3b0: 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a  ng is non-NULL..
b3c0: 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
b3d0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
b3e0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
b3f0: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73  turns.** any res
b400: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74  ult code other t
b410: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  han [SQLITE_OK] 
b420: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  or [SQLITE_NOTFO
b430: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  UND], that means
b440: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53  .** that the VFS
b450: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20   encountered an 
b460: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64  error while hand
b470: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  ling the [PRAGMA
b480: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  ] and the.** com
b490: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  pilation of the 
b4a0: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74  PRAGMA fails wit
b4b0: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68  h an error.  ^Th
b4c0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b4d0: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
b4e0: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61  control occurs a
b4f0: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  t the beginning 
b500: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  of pragma statem
b510: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64  ent analysis and
b520: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c   so.** it is abl
b530: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75  e to override bu
b540: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20  ilt-in [PRAGMA] 
b550: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
b560: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b570: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
b580: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
b590: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
b5a0: 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f  DLER].** file-co
b5b0: 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76  ntrol may be inv
b5c0: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f  oked by SQLite o
b5d0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
b5e0: 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68  ile handle.** sh
b5f0: 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69  ortly after it i
b600: 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65  s opened in orde
b610: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63  r to provide a c
b620: 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61  ustom VFS with a
b630: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20  ccess.** to the 
b640: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79  connections busy
b650: 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
b660: 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  k. The argument 
b670: 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  is of type (void
b680: 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72   **).** - an arr
b690: 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20  ay of two (void 
b6a0: 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66  *) values. The f
b6b0: 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63  irst (void *) ac
b6c0: 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a  tually points.**
b6d0: 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
b6e0: 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28  f type (int (*)(
b6f0: 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64  void *)). In ord
b700: 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  er to invoke the
b710: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
b720: 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68  busy-handler, th
b730: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  is function shou
b740: 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ld be invoked wi
b750: 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76  th the second (v
b760: 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65  oid *) in.** the
b770: 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e   array as the on
b780: 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20  ly argument. If 
b790: 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  it returns non-z
b7a0: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70  ero, then the op
b7b0: 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  eration.** shoul
b7c0: 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66  d be retried. If
b7d0: 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f   it returns zero
b7e0: 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53  , the custom VFS
b7f0: 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20   should abandon 
b800: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f  the.** current o
b810: 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  peration..**.** 
b820: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b830: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
b840: 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f  ].** ^Applicatio
b850: 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65  n can invoke the
b860: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
b870: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c  EMPFILENAME] fil
b880: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20  e-control.** to 
b890: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65  have SQLite gene
b8a0: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72  rate a.** tempor
b8b0: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69  ary filename usi
b8c0: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
b8d0: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f  rithm that is fo
b8e0: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61  llowed to genera
b8f0: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
b900: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45  filenames for TE
b910: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74  MP tables and ot
b920: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65  her internal use
b930: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d  s.  The.** argum
b940: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ent should be a 
b950: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c  char** which wil
b960: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68  l be filled with
b970: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
b980: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
b990: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
b9a0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
b9b0: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c  oc()].  The call
b9c0: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76  er should.** inv
b9d0: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
b9e0: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75  e()] on the resu
b9f0: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65  lt to avoid a me
ba00: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a  mory leak..**.**
ba10: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
ba20: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  NTL_MMAP_SIZE]].
ba30: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
ba40: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
ba50: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
ba60: 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72  used to query or
ba70: 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69   set the.** maxi
ba80: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
ba90: 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65  tes that will be
baa0: 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79   used for memory
bab0: 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20  -mapped I/O..** 
bac0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
bad0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
bae0: 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c  alue of type sql
baf0: 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a  ite3_int64 that.
bb00: 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72  ** is an advisor
bb10: 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  y maximum number
bb20: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
bb30: 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20   file to memory 
bb40: 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69  map.  The.** poi
bb50: 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74  nter is overwrit
bb60: 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64  ten with the old
bb70: 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d   value.  The lim
bb80: 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  it is not change
bb90: 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75  d if.** the valu
bba0: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69  e originally poi
bbb0: 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74  nted to is negat
bbc0: 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ive, and so the 
bbd0: 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a  current limit .*
bbe0: 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64  * can be queried
bbf0: 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61   by passing in a
bc00: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
bc10: 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20  gative number.  
bc20: 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  This.** file-con
bc30: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74  trol is used int
bc40: 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65  ernally to imple
bc50: 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61  ment [PRAGMA mma
bc60: 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  p_size]..**.** <
bc70: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
bc80: 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65  L_TRACE]].** The
bc90: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
bca0: 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  RACE] file contr
bcb0: 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69  ol provides advi
bcc0: 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  sory information
bcd0: 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61  .** to the VFS a
bce0: 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69  bout what the hi
bcf0: 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74  gher layers of t
bd00: 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  he SQLite stack 
bd10: 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68  are doing..** Th
bd20: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
bd30: 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20  is used by some 
bd40: 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61  VFS activity tra
bd50: 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a  cing [shims]..**
bd60: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
bd70: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
bd80: 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68  ed string.  High
bd90: 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65  er layers in the
bda0: 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b  .** SQLite stack
bdb0: 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e   may generate in
bdc0: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20  stances of this 
bdd0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a  file control if.
bde0: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  ** the [SQLITE_U
bdf0: 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20  SE_FCNTL_TRACE] 
be00: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
be10: 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
be20: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
be30: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
be40: 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ED]].** The [SQL
be50: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
be60: 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  VED] file contro
be70: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73  l interprets its
be80: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a   argument as a.*
be90: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
bea0: 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77  integer and it w
beb0: 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20  rites a boolean 
bec0: 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
bed0: 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f  r depending.** o
bee0: 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  n whether or not
bef0: 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65   the file has be
bf00: 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65  en renamed, move
bf10: 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69  d, or deleted si
bf20: 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69  nce it.** was fi
bf30: 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a  rst opened..**.*
bf40: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
bf50: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
bf60: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  ANDLE]].** The [
bf70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
bf80: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f  32_GET_HANDLE] o
bf90: 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65  pcode can be use
bfa0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a  d to obtain the.
bfb0: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61  ** underlying na
bfc0: 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65  tive file handle
bfd0: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
bfe0: 20 61 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20   a file handle. 
bff0: 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f   This file.** co
c000: 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73  ntrol interprets
c010: 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73   its argument as
c020: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
c030: 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64  native file hand
c040: 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73  le and.** writes
c050: 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 76   the resulting v
c060: 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a  alue there..**.*
c070: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c080: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
c090: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  ANDLE]].** The [
c0a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c0b0: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f  32_SET_HANDLE] o
c0c0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
c0d0: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
c0e0: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
c0f0: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
c100: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73  trol method to s
c110: 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e  wap the file han
c120: 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65  dle with the one
c130: 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
c140: 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  y the pArg argum
c150: 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62  ent.  This capab
c160: 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75  ility is used du
c170: 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20  ring testing.** 
c180: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
c190: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
c1a0: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20  hen SQLITE_TEST 
c1b0: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  is defined..**.*
c1c0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c1d0: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d  CNTL_WAL_BLOCK]]
c1e0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
c1f0: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d  FCNTL_WAL_BLOCK]
c200: 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20   is a signal to 
c210: 74 68 65 20 56 46 53 20 6c 61 79 65 72 20 74 68  the VFS layer th
c220: 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62  at it might.** b
c230: 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74  e advantageous t
c240: 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e  o block on the n
c250: 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20  ext WAL lock if 
c260: 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20  the lock is not 
c270: 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61  immediately.** a
c280: 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57  vailable.  The W
c290: 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73 73  AL subsystem iss
c2a0: 75 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20  ues this signal 
c2b0: 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63  during rare.** c
c2c0: 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20  ircumstances in 
c2d0: 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61 20 70  order to fix a p
c2e0: 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f  roblem with prio
c2f0: 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a  rity inversion..
c300: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
c310: 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f  should <em>not</
c320: 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c  em> use this fil
c330: 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a  e-control..**.**
c340: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c350: 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20  NTL_ZIPVFS]].** 
c360: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c370: 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65  L_ZIPVFS] opcode
c380: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
c390: 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20  by zipvfs only. 
c3a0: 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53  All other.** VFS
c3b0: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53   should return S
c3c0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66  QLITE_NOTFOUND f
c3d0: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a  or this opcode..
c3e0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c3f0: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a  TE_FCNTL_RBU]].*
c400: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c410: 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20  NTL_RBU] opcode 
c420: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  is implemented b
c430: 79 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  y the special VF
c440: 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65  S used by.** the
c450: 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f   RBU extension o
c460: 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  nly.  All other 
c470: 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72  VFS should retur
c480: 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e  n SQLITE_NOTFOUN
c490: 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70  D for.** this op
c4a0: 63 6f 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  code.  .**.** <l
c4b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c4c0: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52  _BEGIN_ATOMIC_WR
c4d0: 49 54 45 5d 5d 0a 2a 2a 20 49 66 20 74 68 65 20  ITE]].** If the 
c4e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
c4f0: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
c500: 5d 20 6f 70 63 6f 64 65 20 72 65 74 75 72 6e 73  ] opcode returns
c510: 20 53 51 4c 49 54 45 5f 4f 4b 2c 20 74 68 65 6e   SQLITE_OK, then
c520: 0a 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73  .** the file des
c530: 63 72 69 70 74 6f 72 20 69 73 20 70 6c 61 63 65  criptor is place
c540: 64 20 69 6e 20 22 62 61 74 63 68 20 77 72 69 74  d in "batch writ
c550: 65 20 6d 6f 64 65 22 2c 20 77 68 69 63 68 0a 2a  e mode", which.*
c560: 2a 20 6d 65 61 6e 73 20 61 6c 6c 20 73 75 62 73  * means all subs
c570: 65 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65  equent write ope
c580: 72 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 20  rations will be 
c590: 64 65 66 65 72 72 65 64 20 61 6e 64 20 64 6f 6e  deferred and don
c5a0: 65 0a 2a 2a 20 61 74 6f 6d 69 63 61 6c 6c 79 20  e.** atomically 
c5b0: 61 74 20 74 68 65 20 6e 65 78 74 20 5b 53 51 4c  at the next [SQL
c5c0: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
c5d0: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 20  _ATOMIC_WRITE]. 
c5e0: 20 53 79 73 74 65 6d 73 0a 2a 2a 20 74 68 61 74   Systems.** that
c5f0: 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20   do not support 
c600: 62 61 74 63 68 20 61 74 6f 6d 69 63 20 77 72 69  batch atomic wri
c610: 74 65 73 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  tes will return 
c620: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 2e  SQLITE_NOTFOUND.
c630: 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77 69 6e 67 20 61  .** ^Following a
c640: 20 73 75 63 63 65 73 73 66 75 6c 20 53 51 4c 49   successful SQLI
c650: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
c660: 54 4f 4d 49 43 5f 57 52 49 54 45 20 61 6e 64 20  TOMIC_WRITE and 
c670: 70 72 69 6f 72 20 74 6f 0a 2a 2a 20 74 68 65 20  prior to.** the 
c680: 63 6c 6f 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f  closing [SQLITE_
c690: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
c6a0: 4d 49 43 5f 57 52 49 54 45 5d 20 6f 72 0a 2a 2a  MIC_WRITE] or.**
c6b0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52   [SQLITE_FCNTL_R
c6c0: 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57  OLLBACK_ATOMIC_W
c6d0: 52 49 54 45 5d 2c 20 53 51 4c 69 74 65 20 77 69  RITE], SQLite wi
c6e0: 6c 6c 20 6d 61 6b 65 0a 2a 2a 20 6e 6f 20 56 46  ll make.** no VF
c6f0: 53 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c  S interface call
c700: 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 73  s on the same [s
c710: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 66 69 6c  qlite3_file] fil
c720: 65 20 64 65 73 63 72 69 70 74 6f 72 0a 2a 2a 20  e descriptor.** 
c730: 65 78 63 65 70 74 20 66 6f 72 20 63 61 6c 6c 73  except for calls
c740: 20 74 6f 20 74 68 65 20 78 57 72 69 74 65 20 6d   to the xWrite m
c750: 65 74 68 6f 64 20 61 6e 64 20 74 68 65 20 78 46  ethod and the xF
c760: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
c770: 64 0a 2a 2a 20 77 69 74 68 20 5b 53 51 4c 49 54  d.** with [SQLIT
c780: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
c790: 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  T]..**.** <li>[[
c7a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
c7b0: 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  MIT_ATOMIC_WRITE
c7c0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
c7d0: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41  E_FCNTL_COMMIT_A
c7e0: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63  TOMIC_WRITE] opc
c7f0: 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77  ode causes all w
c800: 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  rite.** operatio
c810: 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70 72 65  ns since the pre
c820: 76 69 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c  vious successful
c830: 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51   call to .** [SQ
c840: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e  LITE_FCNTL_BEGIN
c850: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74  _ATOMIC_WRITE] t
c860: 6f 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 61  o be performed a
c870: 74 6f 6d 69 63 61 6c 6c 79 2e 0a 2a 2a 20 54 68  tomically..** Th
c880: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
c890: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
c8a0: 4f 4b 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  OK] if and only 
c8b0: 69 66 20 74 68 65 20 77 72 69 74 65 73 20 77 65  if the writes we
c8c0: 72 65 0a 2a 2a 20 61 6c 6c 20 70 65 72 66 6f 72  re.** all perfor
c8d0: 6d 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79  med successfully
c8e0: 20 61 6e 64 20 68 61 76 65 20 62 65 65 6e 20 63   and have been c
c8f0: 6f 6d 6d 69 74 74 65 64 20 74 6f 20 70 65 72 73  ommitted to pers
c900: 69 73 74 65 6e 74 20 73 74 6f 72 61 67 65 2e 0a  istent storage..
c910: 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
c920: 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
c930: 20 69 74 20 69 73 20 73 75 63 63 65 73 73 66 75   it is successfu
c940: 6c 2c 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  l, this file con
c950: 74 72 6f 6c 20 74 61 6b 65 73 0a 2a 2a 20 74 68  trol takes.** th
c960: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  e file descripto
c970: 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77  r out of batch w
c980: 72 69 74 65 20 6d 6f 64 65 20 73 6f 20 74 68 61  rite mode so tha
c990: 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  t all subsequent
c9a0: 0a 2a 2a 20 77 72 69 74 65 20 6f 70 65 72 61 74  .** write operat
c9b0: 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e  ions are indepen
c9c0: 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  dent..** ^SQLite
c9d0: 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
c9e0: 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ke SQLITE_FCNTL_
c9f0: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52  COMMIT_ATOMIC_WR
ca00: 49 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61  ITE without.** a
ca10: 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
ca20: 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54  l call to [SQLIT
ca30: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54  E_FCNTL_BEGIN_AT
ca40: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a  OMIC_WRITE]..**.
ca50: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
ca60: 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41  FCNTL_ROLLBACK_A
ca70: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a  TOMIC_WRITE]].**
ca80: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
ca90: 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  TL_ROLLBACK_ATOM
caa0: 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  IC_WRITE] opcode
cab0: 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74   causes all writ
cac0: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20  e.** operations 
cad0: 73 69 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f  since the previo
cae0: 75 73 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  us successful ca
caf0: 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54  ll to .** [SQLIT
cb00: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54  E_FCNTL_BEGIN_AT
cb10: 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62  OMIC_WRITE] to b
cb20: 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  e rolled back..*
cb30: 2a 20 5e 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  * ^This file con
cb40: 74 72 6f 6c 20 74 61 6b 65 73 20 74 68 65 20 66  trol takes the f
cb50: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20 6f  ile descriptor o
cb60: 75 74 20 6f 66 20 62 61 74 63 68 20 77 72 69 74  ut of batch writ
cb70: 65 20 6d 6f 64 65 0a 2a 2a 20 73 6f 20 74 68 61  e mode.** so tha
cb80: 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  t all subsequent
cb90: 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e   write operation
cba0: 73 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65 6e  s are independen
cbb0: 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  t..** ^SQLite wi
cbc0: 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
cbd0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c  SQLITE_FCNTL_ROL
cbe0: 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49  LBACK_ATOMIC_WRI
cbf0: 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20  TE without.** a 
cc00: 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
cc10: 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45   call to [SQLITE
cc20: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
cc30: 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 20 3c  MIC_WRITE]..** <
cc40: 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /ul>.*/.#define 
cc50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
cc60: 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20  KSTATE          
cc70: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
cc80: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f  QLITE_FCNTL_GET_
cc90: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
cca0: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
ccb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c  LITE_FCNTL_SET_L
ccc0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
ccd0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
cce0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45  ITE_FCNTL_LAST_E
ccf0: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
cd00: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
cd10: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
cd20: 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NT              
cd30: 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
cd40: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
cd50: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
cd60: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
cd70: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
cd80: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37  TER            7
cd90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cda0: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
cdb0: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a  ED            8.
cdc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
cdd0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
cde0: 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23  TRY          9.#
cdf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ce00: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20  NTL_PERSIST_WAL 
ce10: 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
ce20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ce30: 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  TL_OVERWRITE    
ce40: 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65            11.#de
ce50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ce60: 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20  L_VFSNAME       
ce70: 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66           12.#def
ce80: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ce90: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
cea0: 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69  RITE    13.#defi
ceb0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
cec0: 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
ced0: 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e         14.#defin
cee0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  e SQLITE_FCNTL_B
cef0: 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20  USYHANDLER      
cf00: 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65        15.#define
cf10: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45   SQLITE_FCNTL_TE
cf20: 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20  MPFILENAME      
cf30: 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20       16.#define 
cf40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
cf50: 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  P_SIZE          
cf60: 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53      18.#define S
cf70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43  QLITE_FCNTL_TRAC
cf80: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
cf90: 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51     19.#define SQ
cfa0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
cfb0: 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20 20  OVED            
cfc0: 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    20.#define SQL
cfd0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20  ITE_FCNTL_SYNC  
cfe0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
cff0: 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   21.#define SQLI
d000: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
d010: 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20 20  PHASETWO        
d020: 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  22.#define SQLIT
d030: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45  E_FCNTL_WIN32_SE
d040: 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32  T_HANDLE       2
d050: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
d060: 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b  _FCNTL_WAL_BLOCK
d070: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
d080: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d090: 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 20  FCNTL_ZIPVFS    
d0a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 0a               25.
d0b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d0c0: 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20 20  CNTL_RBU        
d0d0: 20 20 20 20 20 20 20 20 20 20 20 20 32 36 0a 23              26.#
d0e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d0f0: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20  NTL_VFS_POINTER 
d100: 20 20 20 20 20 20 20 20 20 20 20 32 37 0a 23 64             27.#d
d110: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d120: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
d130: 45 52 20 20 20 20 20 20 20 20 32 38 0a 23 64 65  ER        28.#de
d140: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d150: 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44  L_WIN32_GET_HAND
d160: 4c 45 20 20 20 20 20 20 20 32 39 0a 23 64 65 66  LE       29.#def
d170: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d180: 5f 50 44 42 20 20 20 20 20 20 20 20 20 20 20 20  _PDB            
d190: 20 20 20 20 20 20 20 20 33 30 0a 23 64 65 66 69          30.#defi
d1a0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d1b0: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49  BEGIN_ATOMIC_WRI
d1c0: 54 45 20 20 20 20 20 33 31 0a 23 64 65 66 69 6e  TE     31.#defin
d1d0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
d1e0: 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49  OMMIT_ATOMIC_WRI
d1f0: 54 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65  TE    32.#define
d200: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f   SQLITE_FCNTL_RO
d210: 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52  LLBACK_ATOMIC_WR
d220: 49 54 45 20 20 33 33 0a 0a 2f 2a 20 64 65 70 72  ITE  33../* depr
d230: 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a  ecated names */.
d240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
d250: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
d260: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
d270: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
d280: 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c  FILE.#define SQL
d290: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
d2a0: 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54  YFILE      SQLIT
d2b0: 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b  E_FCNTL_SET_LOCK
d2c0: 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e  PROXYFILE.#defin
d2d0: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
d2e0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
d2f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53  SQLITE_FCNTL_LAS
d300: 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20  T_ERRNO.../*.** 
d310: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
d320: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
d330: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
d340: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
d350: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
d360: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
d370: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
d380: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
d390: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
d3a0: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
d3b0: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
d3c0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
d3d0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
d3e0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
d3f0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
d400: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
d410: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
d420: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
d430: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
d440: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
d450: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
d460: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
d470: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
d480: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
d490: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d4a0: 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73 69  Loadable Extensi
d4b0: 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41  on Thunk.**.** A
d4c0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
d4d0: 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f 61  opaque sqlite3_a
d4e0: 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 75  pi_routines stru
d4f0: 63 74 75 72 65 20 69 73 20 70 61 73 73 65 64 20  cture is passed 
d500: 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20  as.** the third 
d510: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e 74  parameter to ent
d520: 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f  ry points of [lo
d530: 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e  adable extension
d540: 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 72  s].  This.** str
d550: 75 63 74 75 72 65 20 6d 75 73 74 20 62 65 20 74  ucture must be t
d560: 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64 65  ypedefed in orde
d570: 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  r to work around
d580: 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e   compiler warnin
d590: 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c  gs.** on some pl
d5a0: 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65  atforms..*/.type
d5b0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
d5c0: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20  e3_api_routines 
d5d0: 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74  sqlite3_api_rout
d5e0: 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ines;../*.** CAP
d5f0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
d600: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
d610: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
d620: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
d630: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
d640: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
d650: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
d660: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
d670: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
d680: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
d690: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
d6a0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
d6b0: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
d6c0: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
d6d0: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
d6e0: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
d6f0: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
d700: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
d710: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
d720: 56 46 53 20 69 6e 74 65 72 66 61 63 65 20 69 73  VFS interface is
d730: 20 73 6f 6d 65 74 69 6d 65 73 20 65 78 74 65 6e   sometimes exten
d740: 64 65 64 20 62 79 20 61 64 64 69 6e 67 20 6e 65  ded by adding ne
d750: 77 20 6d 65 74 68 6f 64 73 20 6f 6e 74 6f 0a 2a  w methods onto.*
d760: 2a 20 74 68 65 20 65 6e 64 2e 20 20 45 61 63 68  * the end.  Each
d770: 20 74 69 6d 65 20 73 75 63 68 20 61 6e 20 65 78   time such an ex
d780: 74 65 6e 73 69 6f 6e 20 6f 63 63 75 72 73 2c 20  tension occurs, 
d790: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
d7a0: 6c 64 0a 2a 2a 20 69 73 20 69 6e 63 72 65 6d 65  ld.** is increme
d7b0: 6e 74 65 64 2e 20 20 54 68 65 20 69 56 65 72 73  nted.  The iVers
d7c0: 69 6f 6e 20 76 61 6c 75 65 20 73 74 61 72 74 65  ion value starte
d7d0: 64 20 6f 75 74 20 61 73 20 31 20 69 6e 0a 2a 2a  d out as 1 in.**
d7e0: 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e   SQLite [version
d7f0: 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b 64 61 74 65   3.5.0] on [date
d800: 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74 68 65 6e 20  of:3.5.0], then 
d810: 69 6e 63 72 65 61 73 65 64 20 74 6f 20 32 0a 2a  increased to 2.*
d820: 2a 20 77 69 74 68 20 53 51 4c 69 74 65 20 5b 76  * with SQLite [v
d830: 65 72 73 69 6f 6e 20 33 2e 37 2e 30 5d 20 6f 6e  ersion 3.7.0] on
d840: 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e 30 5d 2c   [dateof:3.7.0],
d850: 20 61 6e 64 20 74 68 65 6e 20 69 6e 63 72 65 61   and then increa
d860: 73 65 64 0a 2a 2a 20 74 6f 20 33 20 77 69 74 68  sed.** to 3 with
d870: 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e   SQLite [version
d880: 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b 64 61 74 65   3.7.6] on [date
d890: 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20 41 64 64 69  of:3.7.6].  Addi
d8a0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a  tional fields.**
d8b0: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
d8c0: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
d8d0: 76 66 73 20 6f 62 6a 65 63 74 20 61 6e 64 20 74  vfs object and t
d8e0: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
d8f0: 65 0a 2a 2a 20 6d 61 79 20 69 6e 63 72 65 61 73  e.** may increas
d900: 65 20 61 67 61 69 6e 20 69 6e 20 66 75 74 75 72  e again in futur
d910: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
d920: 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  Lite..** Note th
d930: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65  at the structure
d940: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
d950: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68  e3_vfs object ch
d960: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61  anges in the tra
d970: 6e 73 69 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20  nsition from.** 
d980: 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20  SQLite [version 
d990: 33 2e 35 2e 39 5d 20 74 6f 20 5b 76 65 72 73 69  3.5.9] to [versi
d9a0: 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e 20 5b 64 61  on 3.6.0] on [da
d9b0: 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a 2a 2a 20 61  teof:3.6.0].** a
d9c0: 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73  nd yet the iVers
d9d0: 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f  ion field was no
d9e0: 74 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  t modified..**.*
d9f0: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
da00: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
da10: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
da20: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
da30: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
da40: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
da50: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
da60: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
da70: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
da80: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
da90: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
daa0: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  d sqlite3_vfs ob
dab0: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f  jects are kept o
dac0: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
dad0: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
dae0: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
daf0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
db00: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
db10: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
db20: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
db30: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
db40: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
db50: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
db60: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
db70: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
db80: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
db90: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20  ches the list.  
dba0: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c  Neither the appl
dbb0: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72  ication code nor
dbc0: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c   the VFS.** impl
dbd0: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
dbe0: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20  d use the pNext 
dbf0: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
dc00: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
dc10: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
dc20: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
dc30: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  vfs.** structure
dc40: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
dc50: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
dc60: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
dc70: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
dc80: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
dc90: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
dca0: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
dcb0: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
dcc0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
dcd0: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
dce0: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
dcf0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
dd00: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
dd10: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
dd20: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
dd30: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
dd40: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
dd50: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
dd60: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
dd70: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
dd80: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
dd90: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
dda0: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
ddb0: 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74  Open]].** ^SQLit
ddc0: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
ddd0: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  t the zFilename 
dde0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
ddf0: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  en.** is either 
de00: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
de10: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  r string obtaine
de20: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50  d.** from xFullP
de30: 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61  athname() with a
de40: 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69  n optional suffi
de50: 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  x added..** ^If 
de60: 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65  a suffix is adde
de70: 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61  d to the zFilena
de80: 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74  me parameter, it
de90: 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74   will.** consist
dea0: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22   of a single "-"
deb0: 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f   character follo
dec0: 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74  wed by no more t
ded0: 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e  han.** 11 alphan
dee0: 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d  umeric and/or "-
def0: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
df00: 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72   ^SQLite further
df10: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
df20: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
df30: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
df40: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
df50: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
df60: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20  called. Because 
df70: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
df80: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65  sentence,.** the
df90: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
dfa0: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65  can safely store
dfb0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
dfc0: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
dfd0: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
dfe0: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
dff0: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
e000: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  on..** If the zF
e010: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
e020: 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20  r to xOpen is a 
e030: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
e040: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20  n xOpen.** must 
e050: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74  invent its own t
e060: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f  emporary name fo
e070: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68  r the file.  ^Wh
e080: 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78  enever the .** x
e090: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
e0a0: 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69  er is NULL it wi
e0b0: 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63  ll also be the c
e0c0: 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ase that the.** 
e0d0: 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
e0e0: 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51  will include [SQ
e0f0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
e100: 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20  ONCLOSE]..**.** 
e110: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
e120: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e  nt to xOpen() in
e130: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20  cludes all bits 
e140: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c  set in.** the fl
e150: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
e160: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
e170: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c  ()].  Or if [sql
e180: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
e190: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
e1a0: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74  16()] is used, t
e1b0: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64  hen flags includ
e1c0: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b  es at least.** [
e1d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
e1e0: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
e1f0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a  _OPEN_CREATE]. .
e200: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70  ** If xOpen() op
e210: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d  ens a file read-
e220: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74  only then it set
e230: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a  s *pOutFlags to.
e240: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ** include [SQLI
e250: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
e260: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  ].  Other bits i
e270: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
e280: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e   be set..**.** ^
e290: 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73  (SQLite will als
e2a0: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
e2b0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
e2c0: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
e2d0: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
e2e0: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
e2f0: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
e300: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
e310: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
e320: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
e330: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
e340: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
e350: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
e360: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
e370: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
e380: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
e390: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
e3a0: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
e3b0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
e3c0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
e3d0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
e3e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
e3f0: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
e400: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
e410: 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29  N_WAL].** </ul>)
e420: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  ^.**.** The file
e430: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
e440: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
e450: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
e460: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
e470: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
e480: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
e490: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
e4a0: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
e4b0: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
e4c0: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
e4d0: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
e4e0: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
e4f0: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
e500: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
e510: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
e520: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
e530: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
e540: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
e550: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
e560: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
e570: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
e580: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
e590: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
e5a0: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
e5b0: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
e5c0: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
e5d0: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
e5e0: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
e5f0: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
e600: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
e610: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
e620: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
e630: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
e640: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
e650: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
e660: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
e670: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
e680: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
e690: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
e6a0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
e6b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
e6c0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
e6d0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
e6e0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
e6f0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
e700: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
e710: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
e720: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
e730: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68   is closed.  ^Th
e740: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
e750: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
e760: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72   will be set for
e770: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20   TEMP databases 
e780: 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61  and their journa
e790: 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a  ls, transient.**
e7a0: 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20   databases, and 
e7b0: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a  subjournals..**.
e7c0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
e7d0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20  OPEN_EXCLUSIVE] 
e7e0: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75  flag is always u
e7f0: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69  sed in conjuncti
e800: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
e810: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
e820: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20  TE] flag, which 
e830: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c  are both directl
e840: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74  y.** analogous t
e850: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64  o the O_EXCL and
e860: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f   O_CREAT flags o
e870: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e  f the POSIX open
e880: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20  ().** API.  The 
e890: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
e8a0: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e  USIVE flag, when
e8b0: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65   paired with the
e8c0: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e   .** SQLITE_OPEN
e8d0: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64  _CREATE, is used
e8e0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
e8f0: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c  t file should al
e900: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74  ways.** be creat
e910: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20  ed, and that it 
e920: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69  is an error if i
e930: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73  t already exists
e940: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f  ..** It is <i>no
e950: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e  t</i> used to in
e960: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20  dicate the file 
e970: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
e980: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69   .** for exclusi
e990: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a  ve access..**.**
e9a0: 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46   ^At least szOsF
e9b0: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  ile bytes of mem
e9c0: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  ory are allocate
e9d0: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74  d by SQLite.** t
e9e0: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c  o hold the  [sql
e9f0: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
ea00: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
ea10: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
ea20: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20  ment to xOpen.  
ea30: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
ea40: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74   does not have t
ea50: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68  o.** allocate th
ea60: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20  e structure; it 
ea70: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c  should just fill
ea80: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68   it in.  Note th
ea90: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20  at.** the xOpen 
eaa0: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20  method must set 
eab0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
eac0: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74  .pMethods to eit
ead0: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b  her.** a valid [
eae0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
eaf0: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f  ds] object or to
eb00: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75   NULL.  xOpen mu
eb10: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76  st do.** this ev
eb20: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66  en if the open f
eb30: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78  ails.  SQLite ex
eb40: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73  pects that the s
eb50: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
eb60: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20  hods.** element 
eb70: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66  will be valid af
eb80: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e  ter xOpen return
eb90: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  s regardless of 
eba0: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f  the success.** o
ebb0: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65  r failure of the
ebc0: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a   xOpen call..**.
ebd0: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
ebe0: 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54  .xAccess]].** ^T
ebf0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
ec00: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
ec10: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
ec20: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
ec30: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
ec40: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
ec50: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
ec60: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
ec70: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
ec80: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
ec90: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
eca0: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
ecb0: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
ecc0: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
ecd0: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
ece0: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
ecf0: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
ed00: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
ed10: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
ed20: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
ed30: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
ed40: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
ed50: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
ed60: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
ed70: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63  hname.  The exac
ed80: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
ed90: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
eda0: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
edb0: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
edc0: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49  both  methods. I
edd0: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
ede0: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61  fer.** is not la
edf0: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c  rge enough, [SQL
ee00: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68  ITE_CANTOPEN] sh
ee10: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
ee20: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a  . Since this is.
ee30: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  ** handled as a 
ee40: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
ee50: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65  QLite, vfs imple
ee60: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
ee70: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f  d endeavor.** to
ee80: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
ee90: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e   setting mxPathn
eea0: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69  ame to a suffici
eeb0: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75  ently large valu
eec0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61  e..**.** The xRa
eed0: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
eee0: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69  ep(), xCurrentTi
eef0: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  me(), and xCurre
ef00: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a  ntTimeInt64().**
ef10: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
ef20: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70  not strictly a p
ef30: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73  art of the files
ef40: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20  ystem, but they 
ef50: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20  are.** included 
ef60: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63  in the VFS struc
ef70: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74  ture for complet
ef80: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52  eness..** The xR
ef90: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63  andomness() func
efa0: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f  tion attempts to
efb0: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62   return nBytes b
efc0: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d  ytes.** of good-
efd0: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
efe0: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54  ss into zOut.  T
eff0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
f000: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c  is.** the actual
f010: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
f020: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f   of randomness o
f030: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  btained..** The 
f040: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
f050: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69  causes the calli
f060: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
f070: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
f080: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
f090: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
f0a0: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72  ven.  ^The xCurr
f0b0: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74  entTime().** met
f0c0: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75  hod returns a Ju
f0d0: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20  lian Day Number 
f0e0: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
f0f0: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73  date and time as
f100: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70  .** a floating p
f110: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e  oint value..** ^
f120: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
f130: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72  Int64() method r
f140: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e  eturns, as an in
f150: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61  teger, the Julia
f160: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20  n.** Day Number 
f170: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36  multiplied by 86
f180: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
f190: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
f1a0: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
f1b0: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
f1c0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
f1d0: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
f1e0: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
f1f0: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
f200: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
f210: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
f220: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
f230: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
f240: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
f250: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
f260: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
f270: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
f280: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
f290: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
f2a0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
f2b0: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
f2c0: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
f2d0: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xSetSystemCall()
f2e0: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  , xGetSystemCall
f2f0: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73  (), and xNestSys
f300: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66  temCall() interf
f310: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
f320: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69  used by the SQLi
f330: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20  te core.  These 
f340: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61  optional interfa
f350: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
f360: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65  .** by some VFSe
f370: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20  s to facilitate 
f380: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56  testing of the V
f390: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72  FS code. By over
f3a0: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65  riding .** syste
f3b0: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e  m calls with fun
f3c0: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73  ctions under its
f3d0: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74   control, a test
f3e0: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20   program can.** 
f3f0: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20  simulate faults 
f400: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74  and error condit
f410: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20  ions that would 
f420: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66  otherwise be dif
f430: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70  ficult.** or imp
f440: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63  ossible to induc
f450: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73  e.  The set of s
f460: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74  ystem calls that
f470: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
f480: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f  en.** varies fro
f490: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f  m one VFS to ano
f4a0: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f  ther, and from o
f4b0: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ne version of th
f4c0: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68  e same VFS to th
f4d0: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
f4e0: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
f4f0: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  e these interfac
f500: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61  es must be prepa
f510: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f  red for any.** o
f520: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69  r all of these i
f530: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20  nterfaces to be 
f540: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69  NULL or for thei
f550: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68  r behavior to ch
f560: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65  ange.** from one
f570: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20   release to the 
f580: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
f590: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74  ons must not att
f5a0: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a  empt to access.*
f5b0: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d  * any of these m
f5c0: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56  ethods if the iV
f5d0: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46  ersion of the VF
f5e0: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33  S is less than 3
f5f0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
f600: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
f610: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70  sqlite3_vfs;.typ
f620: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
f630: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
f640: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73  (void);.struct s
f650: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
f660: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
f670: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
f680: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
f690: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33  ber (currently 3
f6a0: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
f6b0: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
f6c0: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
f6d0: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
f6e0: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
f6f0: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
f700: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
f710: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
f720: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
f730: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
f740: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
f750: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
f760: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
f770: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
f780: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
f790: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
f7a0: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
f7b0: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
f7c0: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
f7d0: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
f7e0: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
f7f0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
f800: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
f810: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
f820: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
f830: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
f840: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
f850: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
f860: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
f870: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
f880: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
f890: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
f8a0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
f8b0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
f8c0: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
f8d0: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
f8e0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
f8f0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
f900: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
f910: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
f920: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
f930: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
f940: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
f950: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
f960: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
f970: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
f980: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
f990: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
f9a0: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
f9b0: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
f9c0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
f9d0: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
f9e0: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
f9f0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
fa00: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
fa10: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
fa20: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
fa30: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
fa40: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
fa50: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
fa60: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
fa70: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
fa80: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
fa90: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
faa0: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
fab0: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
fac0: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
fad0: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
fae0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
faf0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
fb00: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
fb10: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
fb20: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
fb30: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
fb40: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
fb50: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
fb60: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72   */.  int (*xCur
fb70: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73  rentTimeInt64)(s
fb80: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c  qlite3_vfs*, sql
fb90: 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20  ite3_int64*);.  
fba0: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
fbb0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
fbc0: 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20   versions 1 and 
fbd0: 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  2 of the sqlite_
fbe0: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
fbf0: 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65   Those below are
fc00: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61   for version 3 a
fc10: 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f  nd greater..  */
fc20: 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73  .  int (*xSetSys
fc30: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
fc40: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
fc50: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
fc60: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a  3_syscall_ptr);.
fc70: 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c    sqlite3_syscal
fc80: 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74  l_ptr (*xGetSyst
fc90: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
fca0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
fcb0: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73   *zName);.  cons
fcc0: 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53  t char *(*xNextS
fcd0: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
fce0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
fcf0: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f  har *zName);.  /
fd00: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
fd10: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
fd20: 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75  versions 1 throu
fd30: 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69  gh 3 of the sqli
fd40: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
fd50: 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   ** New fields m
fd60: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
fd70: 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
fd80: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
fd90: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
fda0: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
fdb0: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
fdc0: 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  . .  */.};../*.*
fdd0: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
fde0: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
fdf0: 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  s VFS method.**.
fe00: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
fe10: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
fe20: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
fe30: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
fe40: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
fe50: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
fe60: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
fe70: 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  t.  They determi
fe80: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
fe90: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
fea0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
feb0: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
fec0: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
fed0: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
fee0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
fef0: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
ff00: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
ff10: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
ff20: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
ff30: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
ff40: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
ff50: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
ff60: 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72  er the named dir
ff70: 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72  ectory is both r
ff80: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
ff90: 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65  able.** (in othe
ffa0: 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65  r words, if file
ffb0: 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20  s can be added, 
ffc0: 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e  removed, and ren
ffd0: 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74  amed within.** t
ffe0: 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a  he directory)..*
fff0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43  * The SQLITE_ACC
10000 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f  ESS_READWRITE co
10010 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e  nstant is curren
10020 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79  tly used only by
10030 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74   the.** [temp_st
10040 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
10050 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68  agma], though th
10060 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20  is could change 
10070 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
10080 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
10090 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
100a0 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
100b0 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
100c0 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
100d0 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
100e0 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51  eadable.  The SQ
100f0 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
10100 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20   constant is.** 
10110 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64  currently unused
10120 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68  , though it migh
10130 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66  t be used in a f
10140 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
10150 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23  .** SQLite..*/.#
10160 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
10170 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
10180 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10190 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
101a0 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20   1   /* Used by 
101b0 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72  PRAGMA temp_stor
101c0 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23  e_directory */.#
101d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
101e0 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
101f0 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a     /* Unused */.
10200 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10210 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
10220 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68  ShmLock VFS meth
10230 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
10240 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
10250 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69   define the vari
10260 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72  ous locking oper
10270 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65  ations.** allowe
10280 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63  d by the xShmLoc
10290 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c  k method of [sql
102a0 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
102b0 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  .  The.** follow
102c0 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79  ing are the only
102d0 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69   legal combinati
102e0 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20  ons of flags to 
102f0 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20  the.** xShmLock 
10300 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
10310 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
10320 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
10330 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
10340 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
10350 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
10360 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
10370 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
10380 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
10390 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
103a0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
103b0 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
103c0 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
103d0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
103e0 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20  When unlocking, 
103f0 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20  the same SHARED 
10400 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61  or EXCLUSIVE fla
10410 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69  g must be suppli
10420 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76  ed as.** was giv
10430 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73  en on the corres
10440 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a  ponding lock.  .
10450 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
10460 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72  ck method can tr
10470 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
10480 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48   unlocked and SH
10490 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65  ARED or.** betwe
104a0 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
104b0 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63  EXCLUSIVE.  It c
104c0 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e  annot transition
104d0 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a   between SHARED.
104e0 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ** and EXCLUSIVE
104f0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
10500 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20  ITE_SHM_UNLOCK  
10510 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
10520 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20  QLITE_SHM_LOCK  
10530 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
10540 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
10550 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69  ED       4.#defi
10560 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58  ne SQLITE_SHM_EX
10570 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a  CLUSIVE    8../*
10580 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
10590 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69  ximum xShmLock i
105a0 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ndex.**.** The x
105b0 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
105c0 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
105d0 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76  thods] may use v
105e0 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
105f0 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65   0 and this uppe
10600 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22  r bound as its "
10610 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74  offset" argument
10620 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
10630 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  core will never 
10640 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69  attempt to acqui
10650 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a  re or release a.
10660 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20  ** lock outside 
10670 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f  of this range.*/
10680 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10690 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20  SHM_NLOCK       
106a0 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   8.../*.** CAPI3
106b0 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
106c0 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
106d0 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
106e0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
106f0 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
10700 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
10710 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e  Lite library.  ^
10720 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
10730 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
10740 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
10750 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
10760 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
10770 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
10780 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73  alize()..** Thes
10790 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
107a0 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69  esigned to aid i
107b0 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  n process initia
107c0 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  lization and.** 
107d0 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65  shutdown on embe
107e0 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57  dded systems.  W
107f0 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69  orkstation appli
10800 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a  cations using.**
10810 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79   SQLite normally
10820 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20   do not need to 
10830 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66  invoke either of
10840 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
10850 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
10860 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10870 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
10880 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
10890 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
108a0 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
108b0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
108c0 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
108d0 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
108e0 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
108f0 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
10900 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
10910 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
10920 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
10930 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
10940 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10950 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20  n().  ^(Only an 
10960 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a  effective call.*
10970 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69  * of sqlite3_ini
10980 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61  tialize() does a
10990 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ny initializatio
109a0 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  n.  All other ca
109b0 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c  lls.** are harml
109c0 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
109d0 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
109e0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
109f0 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
10a00 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
10a10 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61   the first.** ca
10a20 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
10a30 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74  utdown() since t
10a40 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
10a50 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e  initialize().  ^
10a60 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65  (Only.** an effe
10a70 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
10a80 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10a90 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
10aa0 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
10ab0 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63  ll other valid c
10ac0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
10ad0 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68  shutdown() are h
10ae0 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
10af0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ^.**.** The sqli
10b00 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10b10 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
10b20 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71  readsafe, but sq
10b30 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10b40 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65  .** is not.  The
10b50 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10b60 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75  n() interface mu
10b70 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  st only be calle
10b80 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67  d from a.** sing
10b90 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20  le thread.  All 
10ba0 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
10bb0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74  onnections] must
10bc0 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61   be closed and a
10bd0 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ll.** other SQLi
10be0 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73  te resources mus
10bf0 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  t be deallocated
10c00 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69   prior to invoki
10c10 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68  ng.** sqlite3_sh
10c20 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  utdown()..**.** 
10c30 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
10c40 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69  gs, ^sqlite3_ini
10c50 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69  tialize() will i
10c60 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
10c70 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
10c80 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33  ilarly, ^sqlite3
10c90 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77  _shutdown().** w
10ca0 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ill invoke sqlit
10cb0 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
10cc0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
10cd0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
10ce0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
10cf0 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
10d00 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20  ess..** ^If for 
10d10 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c  some reason, sql
10d20 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10d30 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69  ) is unable to i
10d40 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65  nitialize.** the
10d50 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70   library (perhap
10d60 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  s it is unable t
10d70 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65  o allocate a nee
10d80 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63  ded resource suc
10d90 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29  h.** as a mutex)
10da0 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b   it returns an [
10db0 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
10dc0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
10dd0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  K]..**.** ^The s
10de0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10df0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
10e00 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
10e10 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
10e20 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
10e30 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
10e40 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
10e50 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
10e60 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
10e70 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10e80 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
10e90 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
10ea0 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
10eb0 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
10ec0 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
10ed0 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
10ee0 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
10ef0 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
10f00 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
10f10 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
10f20 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
10f30 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
10f40 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e  d.** already.  ^
10f50 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
10f60 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10f70 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
10f80 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a  OMIT_AUTOINIT].*
10f90 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
10fa0 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
10fb0 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
10fc0 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
10fd0 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
10fe0 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
10ff0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
11000 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
11010 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
11020 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
11030 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
11040 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
11050 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
11060 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
11070 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
11080 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
11090 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
110a0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
110b0 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
110c0 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
110d0 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
110e0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
110f0 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
11100 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
11110 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
11120 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
11130 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
11140 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
11150 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11160 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  ith [SQLITE_OMIT
11170 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74  _AUTOINIT] might
11180 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
11190 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
111a0 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
111b0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
111c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
111d0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
111e0 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
111f0 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
11200 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
11210 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
11220 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
11230 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
11240 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
11250 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
11260 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
11270 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
11280 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
11290 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
112a0 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
112b0 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
112c0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
112d0 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
112e0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
112f0 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
11300 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
11310 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
11320 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
11330 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
11340 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
11350 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
11360 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11370 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
11380 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
11390 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
113a0 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
113b0 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
113c0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
113d0 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
113e0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
113f0 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
11400 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11410 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
11420 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
11430 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
11440 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
11450 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
11460 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
11470 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11480 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
11490 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
114a0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
114b0 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
114c0 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
114d0 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
114e0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
114f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
11500 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
11510 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
11520 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
11530 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64  d for Unix, Wind
11540 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a  ows, or OS/2..**
11550 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75   When [custom bu
11560 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72  ilds | built for
11570 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
11580 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20  ].** (using the 
11590 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52  [SQLITE_OS_OTHER
115a0 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =1] compile-time
115b0 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20  .** option) the 
115c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
115d0 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62   supply a suitab
115e0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
115f0 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  n for.** sqlite3
11600 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
11610 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
11620 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    An application
11630 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70  -supplied.** imp
11640 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
11650 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
11660 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
11670 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74  nd().** must ret
11680 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
11690 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
116a0 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
116b0 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
116c0 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73  ailure..*/.int s
116d0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
116e0 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  e(void);.int sql
116f0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f  ite3_shutdown(vo
11700 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
11710 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
11720 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  int sqlite3_os_e
11730 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  nd(void);../*.**
11740 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
11750 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74  guring The SQLit
11760 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
11770 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
11780 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
11790 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67  s used to make g
117a0 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74  lobal configurat
117b0 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
117c0 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  o SQLite in orde
117d0 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65  r to tune SQLite
117e0 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
117f0 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65   needs of.** the
11800 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54   application.  T
11810 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  he default confi
11820 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f  guration is reco
11830 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74  mmended for most
11840 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
11850 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75   and so this rou
11860 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20  tine is usually 
11870 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20  not necessary.  
11880 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65  It is.** provide
11890 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72  d to support rar
118a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77  e applications w
118b0 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64  ith unusual need
118c0 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20  s..**.** <b>The 
118d0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
118e0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
118f0 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68  t threadsafe. Th
11900 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
11910 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61   must ensure tha
11920 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
11930 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
11940 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
11950 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
11960 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
11970 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c  g() is running.<
11980 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  /b>.**.** The sq
11990 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
119a0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20  nterface.** may 
119b0 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
119c0 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
119d0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
119e0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
119f0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
11a00 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
11a10 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
11a20 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49  utdown()]..** ^I
11a30 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  f sqlite3_config
11a40 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74  () is called aft
11a50 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  er [sqlite3_init
11a60 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65  ialize()] and be
11a70 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fore.** [sqlite3
11a80 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65  _shutdown()] the
11a90 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  n it will return
11aa0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
11ab0 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
11ac0 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f  , that ^sqlite3_
11ad0 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
11ae0 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
11af0 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
11b00 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
11b10 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
11b20 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
11b30 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
11b40 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
11b50 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
11b60 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
11b70 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74  r.** [configurat
11b80 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74  ion option] that
11b90 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77   determines.** w
11ba0 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20  hat property of 
11bb0 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20  SQLite is to be 
11bc0 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62  configured.  Sub
11bd0 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
11be0 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64  s.** vary depend
11bf0 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66  ing on the [conf
11c00 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11c10 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
11c20 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
11c30 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67  * ^When a config
11c40 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
11c50 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63  s set, sqlite3_c
11c60 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20  onfig() returns 
11c70 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20  [SQLITE_OK]..** 
11c80 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69  ^If the option i
11c90 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c  s unknown or SQL
11ca0 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
11cb0 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a   set the option.
11cc0 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  ** then this rou
11cd0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e  tine returns a n
11ce0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
11cf0 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ode]..*/.int sql
11d00 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c  ite3_config(int,
11d10 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
11d20 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
11d30 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
11d40 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
11d50 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
11d60 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
11d70 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
11d80 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
11d90 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
11da0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
11db0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11dc0 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
11dd0 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
11de0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
11df0 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
11e00 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
11e10 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
11e20 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
11e30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
11e40 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
11e50 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
11e60 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
11e70 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
11e80 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
11e90 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
11ea0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
11eb0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
11ec0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
11ed0 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
11ee0 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
11ef0 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
11f00 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
11f10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11f20 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
11f30 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
11f40 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
11f50 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
11f60 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
11f70 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
11f80 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
11f90 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
11fa0 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
11fb0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
11fc0 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
11fd0 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
11fe0 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
11ff0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
12000 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
12010 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
12020 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
12030 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
12040 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
12050 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
12060 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
12070 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
12080 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
12090 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
120a0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
120b0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
120c0 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
120d0 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
120e0 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
120f0 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
12100 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
12110 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
12120 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
12130 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
12140 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
12150 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
12160 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
12170 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12180 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
12190 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
121a0 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
121b0 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
121c0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
121d0 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
121e0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
121f0 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
12200 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
12210 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
12220 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
12230 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
12240 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
12250 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
12260 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
12270 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
12280 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
12290 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
122a0 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
122b0 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
122c0 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
122d0 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
122e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
122f0 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
12300 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
12310 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
12320 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
12330 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
12340 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
12350 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
12360 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
12370 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
12380 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
12390 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
123a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
123b0 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
123c0 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
123d0 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
123e0 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
123f0 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
12400 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
12410 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
12420 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
12430 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
12440 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
12450 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
12460 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
12470 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
12480 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
12490 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
124a0 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
124b0 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
124c0 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
124d0 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
124e0 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
124f0 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
12500 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
12510 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
12520 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
12530 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
12540 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
12550 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
12560 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
12570 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
12580 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
12590 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
125a0 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
125b0 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
125c0 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
125d0 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
125e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
125f0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
12600 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
12610 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
12620 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
12630 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
12640 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
12650 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
12660 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
12670 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
12680 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
12690 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
126a0 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
126b0 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
126c0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
126d0 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
126e0 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
126f0 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
12700 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
12710 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
12720 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
12730 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
12740 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
12750 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
12760 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
12770 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
12780 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
12790 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
127a0 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
127b0 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
127c0 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
127d0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
127e0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
127f0 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
12800 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
12810 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
12820 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
12830 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
12840 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
12850 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
12860 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
12870 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
12880 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
12890 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
128a0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
128b0 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
128c0 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
128d0 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
128e0 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
128f0 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
12900 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
12910 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
12920 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
12930 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
12940 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
12950 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
12960 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
12970 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
12980 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
12990 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
129a0 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
129b0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
129c0 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
129d0 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
129e0 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
129f0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
12a00 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65  ASTER] mutex whe
12a10 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  n it invokes.** 
12a20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
12a30 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d  , so the xInit m
12a40 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62  ethod need not b
12a50 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  e threadsafe.  T
12a60 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20  he.** xShutdown 
12a70 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63  method is only c
12a80 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  alled from [sqli
12a90 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
12aa0 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  so it does.** no
12ab0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72  t need to be thr
12ac0 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20  eadsafe either. 
12ad0 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d   For all other m
12ae0 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a  ethods, SQLite.*
12af0 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  * holds the [SQL
12b00 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
12b10 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c  _MEM] mutex as l
12b20 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53  ong as the.** [S
12b30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
12b40 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72  STATUS] configur
12b50 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
12b60 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68  turned on (which
12b70 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66  .** it is by def
12b80 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65  ault) and so the
12b90 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74   methods are aut
12ba0 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61  omatically seria
12bb0 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65  lized..** Howeve
12bc0 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f  r, if [SQLITE_CO
12bd0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
12be0 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  is disabled, the
12bf0 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d  n the other.** m
12c00 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74  ethods must be t
12c10 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73  hreadsafe or els
12c20 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e  e make their own
12c30 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f   arrangements fo
12c40 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69  r.** serializati
12c50 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
12c60 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
12c70 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20  ke xInit() more 
12c80 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75  than once withou
12c90 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67  t an intervening
12ca0 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75  .** call to xShu
12cb0 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65  tdown()..*/.type
12cc0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
12cd0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
12ce0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12cf0 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
12d00 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
12d10 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
12d20 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
12d30 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
12d40 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
12d50 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
12d60 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
12d70 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
12d80 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
12d90 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
12da0 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
12db0 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
12dc0 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
12dd0 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
12de0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
12df0 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
12e00 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
12e10 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
12e20 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
12e30 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
12e40 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
12e50 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
12e60 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
12e70 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
12e80 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
12e90 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
12ea0 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
12eb0 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
12ec0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
12ed0 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
12ee0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
12ef0 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
12f00 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
12f10 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
12f20 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
12f30 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
12f40 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
12f50 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
12f60 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45  on Options.** KE
12f70 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75  YWORDS: {configu
12f80 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a  ration option}.*
12f90 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
12fa0 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
12fb0 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
12fc0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12fd0 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
12fe0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
12ff0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
13000 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
13010 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
13020 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
13030 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13040 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
13050 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
13060 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
13070 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
13080 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13090 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
130a0 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
130b0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
130c0 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
130d0 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
130e0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
130f0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
13100 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
13110 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
13120 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
13130 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
13140 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
13150 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
13160 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
13170 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
13180 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13190 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
131a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
131b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
131c0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d  G_SINGLETHREAD]]
131d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
131e0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
131f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
13200 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
13210 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
13220 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
13230 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
13240 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
13250 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
13260 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
13270 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
13280 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
13290 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
132a0 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
132b0 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
132c0 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
132d0 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
132e0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
132f0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
13300 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13310 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
13320 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
13330 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
13340 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
13350 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
13360 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
13370 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
13380 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
13390 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
133a0 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
133b0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
133c0 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
133d0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
133e0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
133f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
13400 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
13410 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13420 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
13430 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
13440 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  TITHREAD]] <dt>S
13450 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
13460 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
13470 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
13480 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
13490 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
134a0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
134b0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
134c0 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
134d0 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
134e0 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
134f0 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
13500 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
13510 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
13520 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
13530 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
13540 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
13550 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
13560 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
13570 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
13580 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
13590 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
135a0 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
135b0 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
135c0 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
135d0 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
135e0 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
135f0 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
13600 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
13610 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
13620 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
13630 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
13640 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
13650 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
13660 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
13670 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
13680 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
13690 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
136a0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
136b0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
136c0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
136d0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
136e0 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
136f0 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
13700 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
13710 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
13720 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13730 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
13740 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
13750 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
13760 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
13770 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
13780 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13790 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
137a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
137b0 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53  RIALIZED]] <dt>S
137c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
137d0 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
137e0 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
137f0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
13800 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
13810 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
13820 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
13830 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69  mode] to Seriali
13840 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  zed. In other wo
13850 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e  rds, this option
13860 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
13870 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
13880 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
13890 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
138a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
138b0 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
138c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
138d0 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
138e0 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
138f0 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
13900 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
13910 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
13920 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
13930 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
13940 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
13950 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
13960 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
13970 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
13980 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
13990 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
139a0 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
139b0 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
139c0 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
139d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
139e0 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
139f0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
13a00 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
13a10 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
13a20 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
13a30 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
13a40 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
13a50 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
13a60 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
13a70 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
13a80 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
13a90 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
13aa0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
13ab0 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a  set the Serializ
13ac0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
13ad0 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
13ae0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
13af0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
13b00 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
13b10 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
13b20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
13b30 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72  IALIZED configur
13b40 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
13b50 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13b60 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
13b70 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13b80 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
13b90 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
13ba0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
13bb0 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
13bc0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
13bd0 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61  t which is .** a
13be0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
13bf0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
13c00 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
13c10 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
13c20 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
13c30 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
13c40 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
13c50 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
13c60 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f  tion routines to
13c70 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
13c80 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  e of.** the memo
13c90 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
13ca0 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
13cb0 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c  o SQLite.)^ ^SQL
13cc0 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73  ite makes.** its
13cd0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
13ce0 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74  y of the content
13cf0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
13d00 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
13d10 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72  ructure.** befor
13d20 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  e the [sqlite3_c
13d30 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65  onfig()] call re
13d40 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  turns.</dd>.**.*
13d50 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13d60 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  G_GETMALLOC]] <d
13d70 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13d80 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
13d90 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
13da0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
13db0 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65  LLOC option take
13dc0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
13dd0 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
13de0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
13df0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
13e00 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
13e10 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
13e20 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
13e30 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
13e40 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
13e50 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
13e60 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
13e70 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13e80 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
13e90 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
13ea0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
13eb0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
13ec0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13ed0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
13ee0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
13ef0 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
13f00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13f10 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
13f20 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
13f30 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
13f40 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
13f50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41  QLITE_CONFIG_SMA
13f60 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  LL_MALLOC]] <dt>
13f70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d  SQLITE_CONFIG_SM
13f80 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  ALL_MALLOC</dt>.
13f90 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
13fa0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c  ITE_CONFIG_SMALL
13fb0 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74  _MALLOC option t
13fc0 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
13fd0 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74 79 70 65 20  ment of.** type 
13fe0 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
13ff0 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77   as a boolean, w
14000 68 69 63 68 20 69 66 20 74 72 75 65 20 70 72 6f  hich if true pro
14010 76 69 64 65 73 20 61 20 68 69 6e 74 20 74 6f 0a  vides a hint to.
14020 2a 2a 20 53 51 4c 69 74 65 20 74 68 61 74 20 69  ** SQLite that i
14030 74 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 20 6c  t should avoid l
14040 61 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  arge memory allo
14050 63 61 74 69 6f 6e 73 20 69 66 20 70 6f 73 73 69  cations if possi
14060 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ble..** SQLite w
14070 69 6c 6c 20 72 75 6e 20 66 61 73 74 65 72 20 69  ill run faster i
14080 66 20 69 74 20 69 73 20 66 72 65 65 20 74 6f 20  f it is free to 
14090 6d 61 6b 65 20 6c 61 72 67 65 20 6d 65 6d 6f 72  make large memor
140a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 0a 2a  y allocations,.*
140b0 2a 20 62 75 74 20 73 6f 6d 65 20 61 70 70 6c 69  * but some appli
140c0 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 70 72 65  cation might pre
140d0 66 65 72 20 74 6f 20 72 75 6e 20 73 6c 6f 77 65  fer to run slowe
140e0 72 20 69 6e 20 65 78 63 68 61 6e 67 65 20 66 6f  r in exchange fo
140f0 72 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  r.** guarantees 
14100 61 62 6f 75 74 20 6d 65 6d 6f 72 79 20 66 72 61  about memory fra
14110 67 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20  gmentation that 
14120 61 72 65 20 70 6f 73 73 69 62 6c 65 20 69 66 20  are possible if 
14130 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  large.** allocat
14140 69 6f 6e 73 20 61 72 65 20 61 76 6f 69 64 65 64  ions are avoided
14150 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
14160 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e 0a 2a 2a  normally off..**
14170 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14180 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
14190 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c  STATUS]] <dt>SQL
141a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
141b0 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
141c0 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
141d0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f  NFIG_MEMSTATUS o
141e0 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67  ption takes sing
141f0 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
14200 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65  ype int,.** inte
14210 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
14220 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
14230 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
14240 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
14250 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  f.** memory allo
14260 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
14270 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79  s. ^(When memory
14280 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
14290 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69  istics are.** di
142a0 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c  sabled, the foll
142b0 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
142c0 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e  erfaces become n
142d0 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a  on-operational:.
142e0 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  **   <ul>.**   <
142f0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
14300 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20  ory_used()].**  
14310 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
14320 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
14330 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
14340 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
14350 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20  limit64()].**   
14360 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
14370 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  atus64()].**   <
14380 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
14390 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
143a0 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
143b0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
143c0 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
143d0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
143e0 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
143f0 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
14400 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
14410 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
14420 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
14430 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
14440 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
14450 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14460 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64  FIG_SCRATCH]] <d
14470 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14480 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
14490 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f  <dd> The SQLITE_
144a0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f  CONFIG_SCRATCH o
144b0 70 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67  ption is no long
144c0 65 72 20 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 64  er used..** </dd
144d0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
144e0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
144f0 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
14500 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
14510 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
14520 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14530 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e  PAGECACHE option
14540 20 73 70 65 63 69 66 69 65 73 20 61 20 6d 65 6d   specifies a mem
14550 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74  ory pool.** that
14560 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
14570 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
14580 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68   page cache with
14590 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67   the default pag
145a0 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
145b0 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  mentation.  .** 
145c0 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
145d0 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e  on option is a n
145e0 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c 69  o-op if an appli
145f0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61  cation-define pa
14600 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
14610 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f  ementation is lo
14620 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  aded using the [
14630 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14640 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72  ACHE2]..** ^Ther
14650 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
14660 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f  ments to SQLITE_
14670 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
14680 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  : A pointer to.*
14690 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  * 8-byte aligned
146a0 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20   memory (pMem), 
146b0 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
146c0 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65   page cache line
146d0 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
146e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63 68  e number of cach
146f0 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20  e lines (N)..** 
14700 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
14710 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69  should be the si
14720 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ze of the larges
14730 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a  t database page.
14740 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74  ** (a power of t
14750 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
14760 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73  nd 65536) plus s
14770 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20  ome extra bytes 
14780 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
14790 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e   header.  ^The n
147a0 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62  umber of extra b
147b0 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74  ytes needed by t
147c0 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a  he page header.*
147d0 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  * can be determi
147e0 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49 54  ned using [SQLIT
147f0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
14800 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69  HDRSZ]..** ^It i
14810 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72  s harmless, apar
14820 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65  t from the waste
14830 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72  d memory,.** for
14840 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65   the sz paramete
14850 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74  r to be larger t
14860 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20  han necessary.  
14870 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75  The pMem.** argu
14880 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69 74  ment must be eit
14890 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
148a0 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20  er or a pointer 
148b0 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  to an 8-byte.** 
148c0 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66  aligned block of
148d0 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65   memory of at le
148e0 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20  ast sz*N bytes, 
148f0 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75 62  otherwise.** sub
14900 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
14910 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
14920 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73 20  * ^When pMem is 
14930 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65  not NULL, SQLite
14940 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f 20   will strive to 
14950 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  use the memory p
14960 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61  rovided.** to sa
14970 74 69 73 66 79 20 70 61 67 65 20 63 61 63 68 65  tisfy page cache
14980 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20   needs, falling 
14990 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33  back to [sqlite3
149a0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a  _malloc()] if.**
149b0 20 61 20 70 61 67 65 20 63 61 63 68 65 20 6c 69   a page cache li
149c0 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74 68 61  ne is larger tha
149d0 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69 66  n sz bytes or if
149e0 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d   all of the pMem
149f0 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65 78   buffer.** is ex
14a00 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20  hausted..** ^If 
14a10 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64  pMem is NULL and
14a20 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20   N is non-zero, 
14a30 74 68 65 6e 20 65 61 63 68 20 64 61 74 61 62 61  then each databa
14a40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
14a50 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61 6c   does an initial
14a60 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e   bulk allocation
14a70 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20   for page cache 
14a80 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b  memory.** from [
14a90 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14aa0 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f 72  ] sufficient for
14ab0 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20 69   N cache lines i
14ac0 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 20  f N is positive 
14ad0 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e  or.** of -1024*N
14ae0 20 62 79 74 65 73 20 69 66 20 4e 20 69 73 20 6e   bytes if N is n
14af0 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20 61  egative, . ^If a
14b00 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67  dditional.** pag
14b10 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69  e cache memory i
14b20 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20  s needed beyond 
14b30 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
14b40 20 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c 0a   by the initial.
14b50 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  ** allocation, t
14b60 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73 20  hen SQLite goes 
14b70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
14b80 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c 79  oc()] separately
14b90 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64 64   for each.** add
14ba0 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69  itional cache li
14bb0 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ne. </dd>.**.** 
14bc0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14bd0 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  HEAP]] <dt>SQLIT
14be0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
14bf0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
14c00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
14c10 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  AP option specif
14c20 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
14c30 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74  ory buffer .** t
14c40 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
14c50 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
14c60 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
14c70 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
14c80 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f  ds.** beyond tho
14c90 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  se provided for 
14ca0 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
14cb0 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
14cc0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
14cd0 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20  FIG_HEAP option 
14ce0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
14cf0 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  e if SQLite is c
14d00 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
14d10 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45  either [SQLITE_E
14d20 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f  NABLE_MEMSYS3] o
14d30 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
14d40 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65  _MEMSYS5] and re
14d50 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
14d60 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b  _ERROR] if invok
14d70 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
14d80 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65   ^There are thre
14d90 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53  e arguments to S
14da0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
14db0 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20  P:.** An 8-byte 
14dc0 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
14dd0 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
14de0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
14df0 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
14e00 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
14e10 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
14e20 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
14e30 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
14e40 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
14e50 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
14e60 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
14e70 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
14e80 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
14e90 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
14ea0 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
14eb0 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
14ec0 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
14ed0 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
14ee0 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
14ef0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
14f00 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
14f10 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
14f20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68  not NULL then th
14f30 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
14f40 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
14f50 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
14f60 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
14f70 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
14f80 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
14f90 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
14fa0 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
14fb0 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
14fc0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
14fd0 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
14fe0 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
14ff0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
15000 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
15010 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
15020 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
15030 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
15040 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61  t 2**12. Reasona
15050 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f  ble values.** fo
15060 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  r the minimum al
15070 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72  location size ar
15080 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32  e 2**5 through 2
15090 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  **8.</dd>.**.** 
150a0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
150b0 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
150c0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
150d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
150e0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
150f0 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61  _MUTEX option ta
15100 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
15110 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
15120 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
15130 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
15140 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
15150 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
15160 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  ure..** The argu
15170 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61  ment specifies a
15180 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
15190 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
151a0 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a  nes to be used.*
151b0 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d  * in place the m
151c0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
151d0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
151e0 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
151f0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
15200 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
15210 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
15220 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
15230 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
15240 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
15250 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
15260 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
15270 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
15280 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
15290 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
152a0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
152b0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
152c0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
152d0 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
152e0 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
152f0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
15300 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
15310 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
15320 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
15330 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
15340 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
15350 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15360 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
15370 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
15380 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15390 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
153a0 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
153b0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
153c0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
153d0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
153e0 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69  IG_GETMUTEX opti
153f0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
15400 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
15410 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
15420 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
15430 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
15440 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
15450 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
15460 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
15470 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
15480 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
15490 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
154a0 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
154b0 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
154c0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
154d0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
154e0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
154f0 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
15500 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
15510 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
15520 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
15530 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
15540 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
15550 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
15560 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
15570 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
15580 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
15590 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
155a0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
155b0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
155c0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
155d0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
155e0 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
155f0 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
15600 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
15610 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
15620 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
15630 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
15640 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15650 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
15660 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
15670 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
15680 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
15690 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
156a0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
156b0 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
156c0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
156d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
156e0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
156f0 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f  _LOOKASIDE optio
15700 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
15710 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
15720 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61  mine.** the defa
15730 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b  ult size of look
15740 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20  aside memory on 
15750 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63  each [database c
15760 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  onnection]..** T
15770 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15780 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
15790 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
157a0 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
157b0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
157c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
157d0 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
157e0 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
157f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
15800 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49    ^(SQLITE_CONFI
15810 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73  G_LOOKASIDE.** s
15820 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75  ets the <i>defau
15830 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65  lt</i> lookaside
15840 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49   size. The [SQLI
15850 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
15860 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e  ASIDE].** option
15870 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
15880 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
15890 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
158a0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
158b0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
158c0 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
158d0 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
158e0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
158f0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
15900 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15910 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e  FIG_PCACHE2</dt>
15920 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
15930 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
15940 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
15950 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
15960 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a  ent which is .**
15970 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
15980 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
15990 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
159a0 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
159b0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
159c0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20   interface to a 
159d0 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
159e0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
159f0 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d  .)^.** ^SQLite m
15a00 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
15a10 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  he [sqlite3_pcac
15a20 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
15a30 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ect.</dd>.**.** 
15a40 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15a50 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  GETPCACHE2]] <dt
15a60 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
15a70 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  ETPCACHE2</dt>.*
15a80 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
15a90 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
15aa0 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
15ab0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
15ac0 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
15ad0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
15ae0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
15af0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
15b00 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
15b10 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72  s of.** the curr
15b20 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ent page cache i
15b30 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
15b40 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
15b50 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
15b60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15b70 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  G]] <dt>SQLITE_C
15b80 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a  ONFIG_LOG</dt>.*
15b90 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54  * <dd> The SQLIT
15ba0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
15bb0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63  ion is used to c
15bc0 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c  onfigure the SQL
15bd0 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65  ite.** global [e
15be0 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e  rror log]..** (^
15bf0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
15c00 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
15c10 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
15c20 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
15c30 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
15c40 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
15c50 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
15c60 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
15c70 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
15c80 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
15c90 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
15ca0 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
15cb0 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
15cc0 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
15cd0 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
15ce0 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
15cf0 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
15d00 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
15d10 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
15d20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
15d30 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
15d40 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
15d50 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
15d60 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
15d70 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
15d80 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
15d90 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
15da0 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
15db0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
15dc0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
15dd0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
15de0 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
15df0 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
15e00 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
15e10 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
15e20 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
15e30 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
15e40 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
15e50 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
15e60 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
15e70 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
15e80 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
15e90 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
15ea0 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
15eb0 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
15ec0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
15ed0 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
15ee0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
15ef0 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
15f00 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
15f10 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
15f20 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
15f30 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
15f40 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
15f50 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
15f60 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
15f70 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
15f80 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
15f90 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
15fa0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
15fb0 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
15fc0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
15fd0 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
15fe0 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
15ff0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
16000 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
16010 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
16020 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
16030 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
16040 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20  TE_CONFIG_URI]] 
16050 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16060 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54  G_URI.** <dd>^(T
16070 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
16080 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _URI option take
16090 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
160a0 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e  ent of type int.
160b0 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c  .** If non-zero,
160c0 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
160d0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
160e0 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70  nabled. If the p
160f0 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f  arameter is zero
16100 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61  ,.** then URI ha
16110 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
16120 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e  ly disabled.)^ ^
16130 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  If URI handling 
16140 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65  is globally.** e
16150 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65  nabled, all file
16160 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20  names passed to 
16170 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
16180 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
16190 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
161a0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a  e3_open16()] or.
161b0 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ** specified as 
161c0 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d  part of [ATTACH]
161d0 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e   commands are in
161e0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
161f0 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a  s, regardless.**
16200 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
16210 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ot the [SQLITE_O
16220 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
16230 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61   set when the da
16240 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
16250 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
16260 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c  ^If it is global
16270 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c  ly disabled, fil
16280 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e  enames are.** on
16290 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ly interpreted a
162a0 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51  s URIs if the SQ
162b0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c  LITE_OPEN_URI fl
162c0 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
162d0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
162e0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
162f0 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c  ned. ^(By defaul
16300 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  t, URI handling 
16310 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64  is globally.** d
16320 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66  isabled. The def
16330 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62  ault value may b
16340 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d  e changed by com
16350 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a  piling with the.
16360 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  ** [SQLITE_USE_U
16370 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  RI] symbol defin
16380 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ed.)^.**.** [[SQ
16390 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
163a0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
163b0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
163c0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
163d0 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e  EX_SCAN.** <dd>^
163e0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
163f0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
16400 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b  _SCAN option tak
16410 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65  es a single inte
16420 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ger.** argument 
16430 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72  which is interpr
16440 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
16450 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e  n in order to en
16460 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a  able or disable.
16470 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  ** the use of co
16480 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
16490 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
164a0 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79  ans in the query
164b0 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e   optimizer..** ^
164c0 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
164d0 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65  ing is determine
164e0 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c  d.** by the [SQL
164f0 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49  ITE_ALLOW_COVERI
16500 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63  NG_INDEX_SCAN] c
16510 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
16520 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a  on, or is "on".*
16530 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c  * if that compil
16540 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
16550 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65   omitted..** The
16560 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61   ability to disa
16570 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63  ble the use of c
16580 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
16590 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
165a0 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75  cans.** is becau
165b0 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63  se some incorrec
165c0 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79  tly coded legacy
165d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69   applications mi
165e0 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a  ght malfunction.
165f0 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69  ** when the opti
16600 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  mization is enab
16610 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20  led.  Providing 
16620 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a  the ability to.*
16630 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70  * disable the op
16640 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77  timization allow
16650 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67  s the older, bug
16660 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  gy application c
16670 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ode to work.** w
16680 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76  ithout change ev
16690 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65  en with newer ve
166a0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
166b0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
166c0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d  _CONFIG_PCACHE]]
166d0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
166e0 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20  _GETPCACHE]].** 
166f0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16700 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c  G_PCACHE and SQL
16710 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
16720 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  ACHE.** <dd> The
16730 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f  se options are o
16740 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75  bsolete and shou
16750 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62  ld not be used b
16760 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54  y new code..** T
16770 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64  hey are retained
16780 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
16790 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74  ompatibility but
167a0 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e   are now no-ops.
167b0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
167c0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
167d0 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e  SQLLOG]].** <dt>
167e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
167f0 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  LLOG.** <dd>This
16800 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
16810 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c  available if sql
16820 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
16830 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
16840 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f  ITE_ENABLE_SQLLO
16850 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  G] pre-processor
16860 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20   macro defined. 
16870 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
16880 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20  nt should.** be 
16890 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66  a pointer to a f
168a0 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
168b0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
168c0 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61  lite3*,const cha
168d0 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65  r*, int)..** The
168e0 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62   second should b
168f0 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a  e of type (void*
16900 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ). The callback 
16910 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68  is invoked by th
16920 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20  e library.** in 
16930 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63  three separate c
16940 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64  ircumstances, id
16950 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
16960 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
16970 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
16980 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20  rameter. If the 
16990 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
169a0 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20   is 0, then the 
169b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
169c0 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73  ion.** passed as
169d0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
169e0 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65  ment has just be
169f0 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74  en opened. The t
16a00 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
16a10 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66   points to a buf
16a20 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  fer containing t
16a30 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
16a40 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
16a50 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75  e. If the.** fou
16a60 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
16a70 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c   1, then the SQL
16a80 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
16a90 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
16aa0 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ter.** points to
16ab0 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65   has just been e
16ac0 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20  xecuted. Or, if 
16ad0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
16ae0 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a  eter is 2, then.
16af0 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ** the connectio
16b00 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61  n being passed a
16b10 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
16b20 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20  ameter is being 
16b30 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74  closed. The.** t
16b40 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
16b50 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e  s passed NULL In
16b60 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20   this case.  An 
16b70 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67  example of using
16b80 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75   this.** configu
16b90 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61  ration option ca
16ba0 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65  n be seen in the
16bb0 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22   "test_sqllog.c"
16bc0 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a   source file in.
16bd0 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c  ** the canonical
16be0 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74   SQLite source t
16bf0 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ree.</dd>.**.** 
16c00 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16c10 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  MMAP_SIZE]].** <
16c20 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16c30 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64  _MMAP_SIZE.** <d
16c40 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d>^SQLITE_CONFIG
16c50 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73  _MMAP_SIZE takes
16c60 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65   two 64-bit inte
16c70 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74  ger (sqlite3_int
16c80 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  64) values.** th
16c90 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75  at are the defau
16ca0 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  lt mmap size lim
16cb0 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20  it (the default 
16cc0 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b  setting for.** [
16cd0 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
16ce0 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ]) and the maxim
16cf0 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
16d00 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e  size limit..** ^
16d10 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
16d20 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72  ing can be overr
16d30 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61  idden by each da
16d40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16d50 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65  n using.** eithe
16d60 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d  r the [PRAGMA mm
16d70 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64  ap_size] command
16d80 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68  , or by using th
16d90 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
16da0 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
16db0 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54  le control.  ^(T
16dc0 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
16dd0 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20  ed mmap size.** 
16de0 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79  will be silently
16df0 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65   truncated if ne
16e00 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20  cessary so that 
16e10 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65  it does not exce
16e20 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  ed the.** compil
16e30 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
16e40 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
16e50 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
16e60 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
16e70 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
16e80 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68  n.)^.** ^If eith
16e90 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  er argument to t
16ea0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65  his option is ne
16eb0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61  gative, then tha
16ec0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  t argument is.**
16ed0 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20   changed to its 
16ee0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66  compile-time def
16ef0 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ault..**.** [[SQ
16f00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
16f10 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20  2_HEAPSIZE]].** 
16f20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16f30 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
16f40 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
16f50 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
16f60 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e  _HEAPSIZE option
16f70 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
16f80 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a  le if SQLite is.
16f90 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  ** compiled for 
16fa0 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65  Windows with the
16fb0 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d   [SQLITE_WIN32_M
16fc0 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65  ALLOC] pre-proce
16fd0 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65  ssor macro.** de
16fe0 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43  fined. ^SQLITE_C
16ff0 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
17000 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d  SIZE takes a 32-
17010 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
17020 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68  eger value.** th
17030 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  at specifies the
17040 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
17050 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61   the created hea
17060 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  p..**.** [[SQLIT
17070 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
17080 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  HDRSZ]].** <dt>S
17090 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
170a0 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64  CHE_HDRSZ.** <dd
170b0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
170c0 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
170d0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
170e0 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
170f0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
17100 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
17110 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20  eger and writes 
17120 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
17130 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  r the number of 
17140 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70  extra.** bytes p
17150 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64  er page required
17160 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69   for each page i
17170 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  n [SQLITE_CONFIG
17180 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
17190 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78  The amount of ex
171a0 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72  tra space requir
171b0 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65  ed can change de
171c0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
171d0 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67  ompiler,.** targ
171e0 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64  et platform, and
171f0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e   SQLite version.
17200 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
17210 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a  CONFIG_PMASZ]].*
17220 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
17230 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64  FIG_PMASZ.** <dd
17240 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
17250 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e  FIG_PMASZ option
17260 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
17270 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
17280 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65  ** is an unsigne
17290 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65  d integer and se
172a0 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20  ts the "Minimum 
172b0 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68  PMA Size" for th
172c0 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a  e multithreaded.
172d0 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61  ** sorter to tha
172e0 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20  t integer.  The 
172f0 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20  default minimum 
17300 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20  PMA Size is set 
17310 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
17320 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20  E_SORTER_PMASZ] 
17330 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
17340 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64  ion.  New thread
17350 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a  s are launched.*
17360 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73  * to help with s
17370 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77  ort operations w
17380 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65  hen multithreade
17390 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20  d sorting.** is 
173a0 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74  enabled (using t
173b0 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61  he [PRAGMA threa
173c0 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64  ds] command) and
173d0 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63   the amount of c
173e0 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20  ontent.** to be 
173f0 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74  sorted exceeds t
17400 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d  he page size tim
17410 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f  es the minimum o
17420 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41  f the.** [PRAGMA
17430 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74   cache_size] set
17440 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61  ting and this va
17450 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  lue..**.** [[SQL
17460 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
17470 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c  RNL_SPILL]].** <
17480 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17490 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a  _STMTJRNL_SPILL.
174a0 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
174b0 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
174c0 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e 20  NL_SPILL option 
174d0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
174e0 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
174f0 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b 73  * becomes the [s
17500 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c  tatement journal
17510 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20  ] spill-to-disk 
17520 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20  threshold.  .** 
17530 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e  [Statement journ
17540 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69 6e  als] are held in
17550 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74 68   memory until th
17560 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79 74  eir size (in byt
17570 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20 74  es).** exceeds t
17580 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20 61  his threshold, a
17590 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74 68  t which point th
175a0 65 79 20 61 72 65 20 77 72 69 74 74 65 6e 20 74  ey are written t
175b0 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66  o disk..** Or if
175c0 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20 69   the threshold i
175d0 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74 20  s -1, statement 
175e0 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c 77  journals are alw
175f0 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63 6c  ays held.** excl
17600 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f 72  usively in memor
17610 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e 79  y..** Since many
17620 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e   statement journ
17630 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d 65  als never become
17640 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67 20   large, setting 
17650 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68 72  the spill.** thr
17660 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c 75  eshold to a valu
17670 65 20 73 75 63 68 20 61 73 20 36 34 4b 69 42 20  e such as 64KiB 
17680 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64 75  can greatly redu
17690 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  ce the amount of
176a0 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65 64  .** I/O required
176b0 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61 74   to support stat
176c0 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a  ement rollback..
176d0 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  ** The default v
176e0 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73 65  alue for this se
176f0 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f 6c  tting is control
17700 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53  led by the.** [S
17710 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53  QLITE_STMTJRNL_S
17720 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  PILL] compile-ti
17730 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f  me option..** </
17740 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
17750 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
17760 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
17770 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
17780 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
17790 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
177a0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
177b0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
177c0 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
177d0 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
177e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
177f0 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
17800 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
17810 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
17820 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17830 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20  G_GETMALLOC     
17840 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  5  /* sqlite3_me
17850 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
17860 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17870 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20  FIG_SCRATCH     
17880 20 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65    6  /* No longe
17890 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e  r used */.#defin
178a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
178b0 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
178c0 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
178d0 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
178e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
178f0 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
17900 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
17910 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
17920 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17930 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
17940 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
17950 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
17960 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
17970 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
17980 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
17990 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
179a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
179b0 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
179c0 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
179d0 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
179e0 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
179f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
17a00 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
17a10 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
17a20 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
17a30 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
17a40 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
17a50 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
17a60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
17a70 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
17a80 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
17a90 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17aa0 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
17ab0 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
17ac0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17ad0 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
17ae0 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
17af0 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
17b00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
17b10 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
17b20 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
17b30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
17b40 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
17b50 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
17b60 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
17b70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17b80 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
17b90 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
17ba0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
17bb0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
17bc0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
17bd0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
17be0 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
17bf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17c00 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
17c10 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
17c20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
17c30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
17c40 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20  MAP_SIZE    22  
17c50 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
17c60 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
17c70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17c80 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
17c90 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20  EAPSIZE      23 
17ca0 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
17cb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17cc0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
17cd0 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f  RSZ        24  /
17ce0 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64  * int *psz */.#d
17cf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17d00 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20  FIG_PMASZ       
17d10 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75          25  /* u
17d20 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d  nsigned int szPm
17d30 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  a */.#define SQL
17d40 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
17d50 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32  RNL_SPILL      2
17d60 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20  6  /* int nByte 
17d70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17d80 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d  E_CONFIG_SMALL_M
17d90 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 32 37 20  ALLOC        27 
17da0 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 0a   /* boolean */..
17db0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17dc0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
17dd0 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
17de0 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
17df0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
17e00 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
17e10 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
17e20 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
17e30 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
17e40 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
17e50 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
17e60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
17e70 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
17e80 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
17e90 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
17ea0 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
17eb0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
17ec0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
17ed0 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
17ee0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
17ef0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
17f00 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
17f10 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
17f20 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
17f30 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
17f40 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
17f50 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
17f60 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
17f70 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
17f80 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
17f90 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
17fa0 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
17fb0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
17fc0 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
17fd0 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
17fe0 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
17ff0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
18000 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
18010 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
18020 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
18030 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
18040 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
18050 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
18060 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
18070 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
18080 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
18090 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
180a0 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
180b0 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
180c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
180d0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
180e0 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
180f0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
18100 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
18110 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
18120 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
18130 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
18140 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
18150 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
18160 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
18170 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
18180 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
18190 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
181a0 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
181b0 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
181c0 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
181d0 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
181e0 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
181f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
18200 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
18210 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
18220 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
18230 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
18240 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
18250 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
18260 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
18270 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
18280 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
18290 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
182a0 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
182b0 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
182c0 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
182d0 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
182e0 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
182f0 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
18300 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
18310 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
18320 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
18330 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
18340 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
18350 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
18360 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
18370 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
18380 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
18390 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
183a0 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
183b0 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  r multiple of 8.
183c0 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64    ^(The lookasid
183d0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66  e memory.** conf
183e0 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20  iguration for a 
183f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18400 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ion can only be 
18410 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61  changed when tha
18420 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  t.** connection 
18430 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
18440 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65   using lookaside
18450 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f   memory, or in o
18460 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68  ther words.** wh
18470 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20  en the "current 
18480 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20  value" returned 
18490 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64  by.** [sqlite3_d
184a0 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c  b_status](D,[SQL
184b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
184c0 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65  SIDE],...) is ze
184d0 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ro..** Any attem
184e0 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  pt to change the
184f0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
18500 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  y configuration 
18510 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a  when lookaside.*
18520 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75  * memory is in u
18530 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f  se leaves the co
18540 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68  nfiguration unch
18550 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
18560 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  s .** [SQLITE_BU
18570 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  SY].)^</dd>.**.*
18580 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
18590 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
185a0 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  Y</dt>.** <dd> ^
185b0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
185c0 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
185d0 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66   disable the enf
185e0 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b  orcement of.** [
185f0 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
18600 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65  traints].  There
18610 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
18620 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
18630 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
18640 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
18650 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
18660 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46  s 0 to disable F
18670 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a  K enforcement,.*
18680 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
18690 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
186a0 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ent or negative 
186b0 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f  to leave FK enfo
186c0 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61  rcement.** uncha
186d0 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e  nged.  The secon
186e0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
186f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
18700 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
18710 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
18720 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
18730 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e  te whether FK en
18740 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66  forcement is off
18750 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77   or on.** follow
18760 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
18770 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
18780 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
18790 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
187a0 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
187b0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
187c0 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
187d0 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
187e0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
187f0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
18800 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74  ABLE_TRIGGER</dt
18810 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
18820 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
18830 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
18840 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47  ble [CREATE TRIG
18850 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e  GER | triggers].
18860 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
18870 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
18880 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
18890 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
188a0 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
188b0 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
188c0 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73  disable triggers
188d0 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
188e0 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73   enable triggers
188f0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
18900 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
18910 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
18920 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
18930 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
18940 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
18950 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
18960 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
18970 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
18980 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65  her triggers are
18990 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
189a0 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
189b0 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
189c0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
189d0 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
189e0 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
189f0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74  which case the t
18a00 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69  rigger setting i
18a10 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
18a20 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
18a30 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
18a40 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33  NFIG_ENABLE_FTS3
18a50 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a  _TOKENIZER</dt>.
18a60 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
18a70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
18a80 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
18a90 65 20 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65  e the two-argume
18aa0 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  nt.** version of
18ab0 20 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e   the [fts3_token
18ac0 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e  izer()] function
18ad0 20 77 68 69 63 68 20 69 73 20 70 61 72 74 20 6f   which is part o
18ae0 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20  f the.** [FTS3] 
18af0 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68  full-text search
18b00 20 65 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f   engine extensio
18b10 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  n..** There shou
18b20 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
18b30 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
18b40 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
18b50 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
18b60 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
18b70 6f 20 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74  o disable fts3_t
18b80 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a  okenizer() or.**
18b90 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
18ba0 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  ble fts3_tokeniz
18bb0 65 72 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65  er() or negative
18bc0 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
18bd0 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67  tting.** unchang
18be0 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
18bf0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
18c00 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
18c10 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
18c20 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
18c30 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
18c40 74 65 20 77 68 65 74 68 65 72 20 66 74 73 33 5f  te whether fts3_
18c50 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73  tokenizer is dis
18c60 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
18c70 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
18c80 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
18c90 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
18ca0 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
18cb0 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
18cc0 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73  h case the new s
18cd0 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
18ce0 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
18cf0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18d00 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
18d10 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49  BLE_LOAD_EXTENSI
18d20 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ON</dt>.** <dd> 
18d30 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
18d40 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
18d50 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73  r disable the [s
18d60 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
18d70 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65  nsion()].** inte
18d80 72 66 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e  rface independen
18d90 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64  tly of the [load
18da0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51  _extension()] SQ
18db0 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  L function..** T
18dc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  he [sqlite3_enab
18dd0 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
18de0 6e 28 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73  n()] API enables
18df0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74   or disables bot
18e00 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b  h the.** C-API [
18e10 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
18e20 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68  ension()] and th
18e30 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b  e SQL function [
18e40 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
18e50 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
18e60 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
18e70 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
18e80 2a 2a 20 57 68 65 6e 20 74 68 65 20 66 69 72 73  ** When the firs
18e90 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
18ea0 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
18eb0 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65  1, then only the
18ec0 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61   C-API is.** ena
18ed0 62 6c 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  bled and the SQL
18ee0 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e   function remain
18ef0 73 20 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20  s disabled.  If 
18f00 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
18f10 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e  nt to.** this in
18f20 74 65 72 66 61 63 65 20 69 73 20 30 2c 20 74 68  terface is 0, th
18f30 65 6e 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50  en both the C-AP
18f40 49 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75  I and the SQL fu
18f50 6e 63 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62  nction are disab
18f60 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  led..** If the f
18f70 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
18f80 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61   -1, then no cha
18f90 6e 67 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f  nges are made to
18fa0 20 73 74 61 74 65 20 6f 66 20 65 69 74 68 65 72   state of either
18fb0 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72   the.** C-API or
18fc0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
18fd0 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  n..** The second
18fe0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
18ff0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
19000 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
19010 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
19020 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
19030 65 20 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74  e whether [sqlit
19040 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
19050 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  n()] interface.*
19060 2a 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72  * is disabled or
19070 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69   enabled followi
19080 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
19090 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
190a0 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20  ter may.** be a 
190b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
190c0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
190d0 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e  new setting is n
190e0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
190f0 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
19100 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
19110 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c  NFIG_MAINDBNAME<
19120 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
19130 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
19140 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
19150 6e 61 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69  name of the "mai
19160 6e 22 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73  n" database.** s
19170 63 68 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c  chema.  ^The sol
19180 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
19190 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e  pointer to a con
191a0 73 74 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e  stant UTF8 strin
191b0 67 0a 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20  g.** which will 
191c0 62 65 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73  become the new s
191d0 63 68 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c  chema name in pl
191e0 61 63 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20  ace of "main".  
191f0 5e 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20  ^SQLite.** does 
19200 6e 6f 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  not make a copy 
19210 6f 66 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20  of the new main 
19220 73 63 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69  schema name stri
19230 6e 67 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69  ng, so the appli
19240 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65  cation.** must e
19250 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61  nsure that the a
19260 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
19270 6e 74 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49  nto this DBCONFI
19280 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68  G option is unch
19290 61 6e 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61  anged.** until a
192a0 66 74 65 72 20 74 68 65 20 64 61 74 61 62 61 73  fter the databas
192b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
192c0 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ses..** </dd>.**
192d0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
192e0 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f  BCONFIG_NO_CKPT_
192f0 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a  ON_CLOSE</dt>.**
19300 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77   <dd> Usually, w
19310 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 69  hen a database i
19320 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c  n wal mode is cl
19330 6f 73 65 64 20 6f 72 20 64 65 74 61 63 68 65 64  osed or detached
19340 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61   from a .** data
19350 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c  base handle, SQL
19360 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 68  ite checks if th
19370 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61  is will mean tha
19380 74 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20  t there are now 
19390 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  no .** connectio
193a0 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65  ns at all to the
193b0 20 64 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f   database. If so
193c0 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20  , it performs a 
193d0 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f  checkpoint .** o
193e0 70 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20  peration before 
193f0 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e  closing the conn
19400 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74  ection. This opt
19410 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20  ion may be used 
19420 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74  to.** override t
19430 68 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54  his behaviour. T
19440 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
19450 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69  er passed to thi
19460 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69  s operation.** i
19470 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 6e  s an integer - n
19480 6f 6e 2d 7a 65 72 6f 20 74 6f 20 64 69 73 61 62  on-zero to disab
19490 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f  le checkpoints-o
194a0 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f  n-close, or zero
194b0 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74   (the.** default
194c0 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d  ) to enable them
194d0 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  . The second par
194e0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
194f0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
19500 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20  r.** into which 
19510 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
19520 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
19530 65 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74  ether checkpoint
19540 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61  s-on-close.** ha
19550 76 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64  ve been disabled
19560 20 2d 20 30 20 69 66 20 74 68 65 79 20 61 72 65   - 0 if they are
19570 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31   not disabled, 1
19580 20 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a   if they are..**
19590 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 64 74 3e 53 51   </dd>.** <dt>SQ
195a0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
195b0 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74 3e 0a 2a  ABLE_QPSG</dt>.*
195c0 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49  * <dd>^(The SQLI
195d0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
195e0 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f 6e 20 61  LE_QPSG option a
195f0 63 74 69 76 61 74 65 73 20 6f 72 20 64 65 61 63  ctivates or deac
19600 74 69 76 61 74 65 73 0a 2a 2a 20 74 68 65 20 5b  tivates.** the [
19610 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 73 74  query planner st
19620 61 62 69 6c 69 74 79 20 67 75 61 72 61 6e 74 65  ability guarante
19630 65 5d 20 28 51 50 53 47 29 2e 20 20 57 68 65 6e  e] (QPSG).  When
19640 20 74 68 65 20 51 50 53 47 20 69 73 20 61 63 74   the QPSG is act
19650 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e 67 6c 65  ive,.** a single
19660 20 53 51 4c 20 71 75 65 72 79 20 73 74 61 74 65   SQL query state
19670 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77 61 79 73  ment will always
19680 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 61 6c   use the same al
19690 67 6f 72 69 74 68 6d 20 72 65 67 61 72 64 6c 65  gorithm regardle
196a0 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75 65 73 20  ss.** of values 
196b0 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  of [bound parame
196c0 74 65 72 73 5d 2e 29 5e 20 54 68 65 20 51 50 53  ters].)^ The QPS
196d0 47 20 64 69 73 61 62 6c 65 73 20 73 6f 6d 65 20  G disables some 
196e0 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 61 74 69  query optimizati
196f0 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c 6f 6f 6b  ons.** that look
19700 20 61 74 20 74 68 65 20 76 61 6c 75 65 73 20 6f   at the values o
19710 66 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  f bound paramete
19720 72 73 2c 20 77 68 69 63 68 20 63 61 6e 20 6d 61  rs, which can ma
19730 6b 65 20 73 6f 6d 65 20 71 75 65 72 69 65 73 0a  ke some queries.
19740 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42 75 74 20  ** slower.  But 
19750 74 68 65 20 51 50 53 47 20 68 61 73 20 74 68 65  the QPSG has the
19760 20 61 64 76 61 6e 74 61 67 65 20 6f 66 20 6d 6f   advantage of mo
19770 72 65 20 70 72 65 64 69 63 74 61 62 6c 65 20 62  re predictable b
19780 65 68 61 76 69 6f 72 2e 20 20 57 69 74 68 0a 2a  ehavior.  With.*
19790 2a 20 74 68 65 20 51 50 53 47 20 61 63 74 69 76  * the QPSG activ
197a0 65 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  e, SQLite will a
197b0 6c 77 61 79 73 20 75 73 65 20 74 68 65 20 73 61  lways use the sa
197c0 6d 65 20 71 75 65 72 79 20 70 6c 61 6e 20 69 6e  me query plan in
197d0 20 74 68 65 20 66 69 65 6c 64 20 61 73 0a 2a 2a   the field as.**
197e0 20 77 61 73 20 75 73 65 64 20 64 75 72 69 6e 67   was used during
197f0 20 74 65 73 74 69 6e 67 20 69 6e 20 74 68 65 20   testing in the 
19800 6c 61 62 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  lab..** </dd>.**
19810 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
19820 4e 46 49 47 5f 46 55 4c 4c 5f 45 51 50 3c 2f 64  NFIG_FULL_EQP</d
19830 74 3e 0a 2a 2a 20 3c 64 64 3e 20 42 79 20 64 65  t>.** <dd> By de
19840 66 61 75 6c 74 2c 20 74 68 65 20 6f 75 74 70 75  fault, the outpu
19850 74 20 6f 66 20 45 58 50 4c 41 49 4e 20 51 55 45  t of EXPLAIN QUE
19860 52 59 20 50 4c 41 4e 20 63 6f 6d 6d 61 6e 64 73  RY PLAN commands
19870 20 64 6f 65 73 20 6e 6f 74 20 0a 2a 2a 20 69 6e   does not .** in
19880 63 6c 75 64 65 20 6f 75 74 70 75 74 20 66 6f 72  clude output for
19890 20 61 6e 79 20 6f 70 65 72 61 74 69 6f 6e 73 20   any operations 
198a0 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 72 69  performed by tri
198b0 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 54  gger programs. T
198c0 68 69 73 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73  his.** option is
198d0 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
198e0 63 6c 65 61 72 20 28 74 68 65 20 64 65 66 61 75  clear (the defau
198f0 6c 74 29 20 61 20 66 6c 61 67 20 74 68 61 74 20  lt) a flag that 
19900 67 6f 76 65 72 6e 73 20 74 68 69 73 0a 2a 2a 20  governs this.** 
19910 62 65 68 61 76 69 6f 72 2e 20 54 68 65 20 66 69  behavior. The fi
19920 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 70 61  rst parameter pa
19930 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f 70 65  ssed to this ope
19940 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 69 6e 74  ration is an int
19950 65 67 65 72 20 2d 0a 2a 2a 20 6e 6f 6e 2d 7a 65  eger -.** non-ze
19960 72 6f 20 74 6f 20 65 6e 61 62 6c 65 20 6f 75 74  ro to enable out
19970 70 75 74 20 66 6f 72 20 74 72 69 67 67 65 72 20  put for trigger 
19980 70 72 6f 67 72 61 6d 73 2c 20 6f 72 20 7a 65 72  programs, or zer
19990 6f 20 74 6f 20 64 69 73 61 62 6c 65 20 69 74 2e  o to disable it.
199a0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
199b0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
199c0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
199d0 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 20 69  ger into which i
199e0 73 20 77 72 69 74 74 65 6e 20 0a 2a 2a 20 30 20  s written .** 0 
199f0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
19a00 20 77 68 65 74 68 65 72 20 6f 75 74 70 75 74 2d   whether output-
19a10 66 6f 72 2d 74 72 69 67 67 65 72 73 20 68 61 73  for-triggers has
19a20 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d   been disabled -
19a30 20 30 20 69 66 20 0a 2a 2a 20 69 74 20 69 73 20   0 if .** it is 
19a40 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20  not disabled, 1 
19a50 69 66 20 69 74 20 69 73 2e 20 20 0a 2a 2a 20 3c  if it is.  .** <
19a60 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  /dd>.** </dl>.*/
19a70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19a80 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e  DBCONFIG_MAINDBN
19a90 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 31  AME            1
19aa0 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63 68 61  000 /* const cha
19ab0 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  r* */.#define SQ
19ac0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
19ad0 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 20 20  OKASIDE         
19ae0 20 20 20 20 31 30 30 31 20 2f 2a 20 76 6f 69 64      1001 /* void
19af0 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
19b00 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
19b10 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
19b20 20 20 20 20 20 20 20 20 20 20 20 31 30 30 32 20             1002 
19b30 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
19b40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
19b50 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
19b60 49 47 47 45 52 20 20 20 20 20 20 20 20 31 30 30  IGGER        100
19b70 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  3 /* int int* */
19b80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19b90 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
19ba0 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20 31  FTS3_TOKENIZER 1
19bb0 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  004 /* int int* 
19bc0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19bd0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
19be0 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e  E_LOAD_EXTENSION
19bf0 20 31 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e 74   1005 /* int int
19c00 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
19c10 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f  ITE_DBCONFIG_NO_
19c20 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20 20  CKPT_ON_CLOSE   
19c30 20 20 20 31 30 30 36 20 2f 2a 20 69 6e 74 20 69     1006 /* int i
19c40 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
19c50 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
19c60 4e 41 42 4c 45 5f 51 50 53 47 20 20 20 20 20 20  NABLE_QPSG      
19c70 20 20 20 20 20 31 30 30 37 20 2f 2a 20 69 6e 74       1007 /* int
19c80 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
19c90 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
19ca0 5f 46 55 4c 4c 5f 45 51 50 20 20 20 20 20 20 20  _FULL_EQP       
19cb0 20 20 20 20 20 20 20 31 30 30 38 20 2f 2a 20 69         1008 /* i
19cc0 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 2f 2a 0a 2a  nt int* */../*.*
19cd0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
19ce0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
19cf0 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
19d00 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  des.** METHOD: s
19d10 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
19d20 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
19d30 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
19d40 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
19d50 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
19d60 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
19d70 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
19d80 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
19d90 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
19da0 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
19db0 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
19dc0 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
19dd0 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
19de0 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ty..*/.int sqlit
19df0 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
19e00 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
19e10 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
19e20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19e30 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
19e40 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
19e50 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  ite3.**.** ^Each
19e60 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53   entry in most S
19e70 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78  QLite tables (ex
19e80 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55  cept for [WITHOU
19e90 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29  T ROWID] tables)
19ea0 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65  .** has a unique
19eb0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a   64-bit signed.*
19ec0 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61  * integer key ca
19ed0 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20  lled the [ROWID 
19ee0 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65  | "rowid"]. ^The
19ef0 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
19f00 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
19f10 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
19f20 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
19f30 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
19f40 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
19f50 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
19f60 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
19f70 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
19f80 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e  lared columns. ^
19f90 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
19fa0 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
19fb0 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52  type [INTEGER PR
19fc0 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20  IMARY KEY] then 
19fd0 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  that column.** i
19fe0 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20  s another alias 
19ff0 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a  for the rowid..*
1a000 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1a010 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
1a020 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65  wid(D) interface
1a030 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72 6e 73   usually returns
1a040 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a   the [rowid] of.
1a050 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  ** the most rece
1a060 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  nt successful [I
1a070 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f  NSERT] into a ro
1a080 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69  wid table or [vi
1a090 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20  rtual table].** 
1a0a0 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  on database conn
1a0b0 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72  ection D. ^Inser
1a0c0 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54  ts into [WITHOUT
1a0d0 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61   ROWID] tables a
1a0e0 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64  re not.** record
1a0f0 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63 65  ed. ^If no succe
1a100 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20  ssful [INSERT]s 
1a110 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65  into rowid table
1a120 73 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  s have ever occu
1a130 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20  rred .** on the 
1a140 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a150 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c 69  ion D, then sqli
1a160 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1a170 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73  rowid(D) returns
1a180 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a   .** zero..**.**
1a190 20 41 73 20 77 65 6c 6c 20 61 73 20 62 65 69 6e   As well as bein
1a1a0 67 20 73 65 74 20 61 75 74 6f 6d 61 74 69 63 61  g set automatica
1a1b0 6c 6c 79 20 61 73 20 72 6f 77 73 20 61 72 65 20  lly as rows are 
1a1c0 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 64 61  inserted into da
1a1d0 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73  tabase.** tables
1a1e0 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
1a1f0 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e  rned by this fun
1a200 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 74  ction may be set
1a210 20 65 78 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a   explicitly by.*
1a220 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c  * [sqlite3_set_l
1a230 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1a240 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76  ()].**.** Some v
1a250 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
1a260 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
1a270 20 49 4e 53 45 52 54 20 72 6f 77 73 20 69 6e 74   INSERT rows int
1a280 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 61  o rowid tables a
1a290 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d  s.** part of com
1a2a0 6d 69 74 74 69 6e 67 20 61 20 74 72 61 6e 73 61  mitting a transa
1a2b0 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66  ction (e.g. to f
1a2c0 6c 75 73 68 20 64 61 74 61 20 61 63 63 75 6d 75  lush data accumu
1a2d0 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a  lated in memory.
1a2e0 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20  ** to disk). In 
1a2f0 74 68 69 73 20 63 61 73 65 20 73 75 62 73 65 71  this case subseq
1a300 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74 68  uent calls to th
1a310 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
1a320 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20  rn the rowid.** 
1a330 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1a340 74 68 65 73 65 20 69 6e 74 65 72 6e 61 6c 20 49  these internal I
1a350 4e 53 45 52 54 20 6f 70 65 72 61 74 69 6f 6e 73  NSERT operations
1a360 2c 20 77 68 69 63 68 20 6c 65 61 64 73 20 74 6f  , which leads to
1a370 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76 65   .** unintuitive
1a380 20 72 65 73 75 6c 74 73 2e 20 56 69 72 74 75 61   results. Virtua
1a390 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
1a3a0 74 61 74 69 6f 6e 73 20 74 68 61 74 20 64 6f 20  tations that do 
1a3b0 77 72 69 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a  write to rowid.*
1a3c0 2a 20 74 61 62 6c 65 73 20 69 6e 20 74 68 69 73  * tables in this
1a3d0 20 77 61 79 20 63 61 6e 20 61 76 6f 69 64 20 74   way can avoid t
1a3e0 68 69 73 20 70 72 6f 62 6c 65 6d 20 62 79 20 72  his problem by r
1a3f0 65 73 74 6f 72 69 6e 67 20 74 68 65 20 6f 72 69  estoring the ori
1a400 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20  ginal .** rowid 
1a410 76 61 6c 75 65 20 75 73 69 6e 67 20 5b 73 71 6c  value using [sql
1a420 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
1a430 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 62 65  sert_rowid()] be
1a440 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 20 0a  fore returning .
1a450 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68  ** control to th
1a460 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  e user..**.** ^(
1a470 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
1a480 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
1a490 72 69 67 67 65 72 20 74 68 65 6e 20 74 68 69 73  rigger then this
1a4a0 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a   routine will .*
1a4b0 2a 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f  * return the [ro
1a4c0 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65  wid] of the inse
1a4d0 72 74 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67  rted row as long
1a4e0 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
1a4f0 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20  is .** running. 
1a500 4f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  Once the trigger
1a510 20 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74   program ends, t
1a520 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1a530 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  d .** by this ro
1a540 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
1a550 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66   what it was bef
1a560 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
1a570 77 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a  was fired.)^.**.
1a580 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
1a590 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
1a5a0 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
1a5b0 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
1a5c0 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
1a5d0 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
1a5e0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
1a5f0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1a600 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
1a610 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
1a620 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
1a630 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
1a640 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
1a650 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
1a660 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
1a670 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
1a680 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
1a690 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
1a6a0 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
1a6b0 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
1a6c0 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
1a6d0 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
1a6e0 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
1a6f0 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
1a700 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
1a710 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
1a720 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
1a730 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
1a740 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
1a750 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
1a760 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
1a770 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
1a780 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
1a790 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
1a7a0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
1a7b0 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
1a7c0 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
1a7d0 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
1a7e0 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
1a7f0 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
1a800 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
1a810 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
1a820 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
1a830 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
1a840 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
1a850 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
1a860 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
1a870 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
1a880 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1a890 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
1a8a0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
1a8b0 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
1a8c0 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
1a8d0 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
1a8e0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1a8f0 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
1a900 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
1a910 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
1a920 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
1a930 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
1a940 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
1a950 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
1a960 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
1a970 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
1a980 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
1a990 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
1a9a0 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
1a9b0 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
1a9c0 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
1a9d0 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
1a9e0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
1a9f0 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  wid]..*/.sqlite3
1aa00 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
1aa10 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1aa20 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1aa30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
1aa40 20 74 68 65 20 4c 61 73 74 20 49 6e 73 65 72 74   the Last Insert
1aa50 20 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a   Rowid value..**
1aa60 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1aa70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1aa80 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65  e3_set_last_inse
1aa90 72 74 5f 72 6f 77 69 64 28 44 2c 20 52 29 20 6d  rt_rowid(D, R) m
1aaa0 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65  ethod allows the
1aab0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a   application to.
1aac0 2a 2a 20 73 65 74 20 74 68 65 20 76 61 6c 75 65  ** set the value
1aad0 20 72 65 74 75 72 6e 65 64 20 62 79 20 63 61 6c   returned by cal
1aae0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61 73  ling sqlite3_las
1aaf0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
1ab00 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f  ) to R .** witho
1ab10 75 74 20 69 6e 73 65 72 74 69 6e 67 20 61 20 72  ut inserting a r
1ab20 6f 77 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  ow into the data
1ab30 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  base..*/.void sq
1ab40 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69  lite3_set_last_i
1ab50 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
1ab60 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  te3*,sqlite3_int
1ab70 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  64);../*.** CAPI
1ab80 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
1ab90 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
1aba0 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f  odified.** METHO
1abb0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1abc0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
1abd0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
1abe0 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66  er of rows modif
1abf0 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ied, inserted or
1ac00 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74  .** deleted by t
1ac10 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
1ac20 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
1ac30 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
1ac40 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
1ac50 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
1ac60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63   connection spec
1ac70 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c  ified by the onl
1ac80 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  y parameter..** 
1ac90 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f  ^Executing any o
1aca0 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c  ther type of SQL
1acb0 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
1acc0 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76  not modify the v
1acd0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
1ace0 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f   by this functio
1acf0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63  n..**.** ^Only c
1ad00 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65  hanges made dire
1ad10 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45  ctly by the INSE
1ad20 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
1ad30 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61  LETE statement a
1ad40 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
1ad50 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61   - auxiliary cha
1ad60 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
1ad70 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
1ad80 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20   triggers], .** 
1ad90 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
1ada0 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43  ions] or [REPLAC
1adb0 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  E] constraint re
1adc0 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74  solution are not
1add0 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a   counted..** .**
1ade0 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69   Changes to a vi
1adf0 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
1ae00 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b  rcepted by .** [
1ae10 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
1ae20 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20  er | INSTEAD OF 
1ae30 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f  triggers] are no
1ae40 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20  t counted. ^The 
1ae50 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e  value .** return
1ae60 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68  ed by sqlite3_ch
1ae70 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74  anges() immediat
1ae80 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53  ely after an INS
1ae90 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a  ERT, UPDATE or .
1aea0 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  ** DELETE statem
1aeb0 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65  ent run on a vie
1aec0 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  w is always zero
1aed0 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d  . Only changes m
1aee0 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20  ade to real .** 
1aef0 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74  tables are count
1af00 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73  ed..**.** Things
1af10 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69   are more compli
1af20 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c  cated if the sql
1af30 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66  ite3_changes() f
1af40 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78  unction is.** ex
1af50 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74  ecuted while a t
1af60 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69  rigger program i
1af70 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20  s running. This 
1af80 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68  may happen if th
1af90 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65  e.** program use
1afa0 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  s the [changes()
1afb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20   SQL function], 
1afc0 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72  or if some other
1afd0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
1afe0 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71  ction invokes sq
1aff0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
1b000 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74  directly. Essent
1b010 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75  ially:.** .** <u
1b020 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42  l>.**   <li> ^(B
1b030 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61  efore entering a
1b040 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1b050 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1b060 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  ned by.**       
1b070 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1b080 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73  () function is s
1b090 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20  aved. After the 
1b0a0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
1b0b0 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66  .**        has f
1b0c0 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69  inished, the ori
1b0d0 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72  ginal value is r
1b0e0 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a  estored.)^.** .*
1b0f0 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69  *   <li> ^(Withi
1b100 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  n a trigger prog
1b110 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c  ram each INSERT,
1b120 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45   UPDATE and DELE
1b130 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74  TE .**        st
1b140 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65  atement sets the
1b150 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1b160 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  by sqlite3_chang
1b170 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  es() .**        
1b180 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  upon completion 
1b190 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f  as normal. Of co
1b1a0 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65  urse, this value
1b1b0 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64   will not includ
1b1c0 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79  e .**        any
1b1d0 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d   changes perform
1b1e0 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65  ed by sub-trigge
1b1f0 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74  rs, as the sqlit
1b200 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a  e3_changes() .**
1b210 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69          value wi
1b220 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20  ll be saved and 
1b230 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65  restored after e
1b240 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20  ach sub-trigger 
1b250 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f  has run.)^.** </
1b260 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73  ul>.** .** ^This
1b270 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74   means that if t
1b280 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c  he changes() SQL
1b290 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69   function (or si
1b2a0 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a  milar) is used.*
1b2b0 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49  * by the first I
1b2c0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
1b2d0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
1b2e0 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
1b2f0 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72  er, it .** retur
1b300 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20  ns the value as 
1b310 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c  set when the cal
1b320 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62  ling statement b
1b330 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a  egan executing..
1b340 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65  ** ^If it is use
1b350 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
1b360 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75  or subsequent su
1b370 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ch statement wit
1b380 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a  hin a trigger .*
1b390 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76  * program, the v
1b3a0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65  alue returned re
1b3b0 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65  flects the numbe
1b3c0 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
1b3d0 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72  ed by the .** pr
1b3e0 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55  evious INSERT, U
1b3f0 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
1b400 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
1b410 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
1b420 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
1b430 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
1b440 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
1b450 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
1b460 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
1b470 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
1b480 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
1b490 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
1b4a0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
1b4b0 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
1b4c0 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
1b4d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1b4e0 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
1b4f0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1b500 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
1b510 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
1b520 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
1b530 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
1b540 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
1b550 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
1b560 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
1b570 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b580 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
1b590 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
1b5a0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1b5b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
1b5c0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1b5d0 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
1b5e0 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c  f rows inserted,
1b5f0 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20   modified or.** 
1b600 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b  deleted by all [
1b610 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45  INSERT], [UPDATE
1b620 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
1b630 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74  atements complet
1b640 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  ed.** since the 
1b650 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b660 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20  ion was opened, 
1b670 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20  including those 
1b680 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70  executed as.** p
1b690 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70  art of trigger p
1b6a0 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74  rograms. ^Execut
1b6b0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79  ing any other ty
1b6c0 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  pe of SQL statem
1b6d0 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ent.** does not 
1b6e0 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65  affect the value
1b6f0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1b700 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1b710 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68  es()..** .** ^Ch
1b720 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61  anges made as pa
1b730 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b  rt of [foreign k
1b740 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
1b750 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a  included in the.
1b760 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68  ** count, but th
1b770 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74  ose made as part
1b780 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73   of REPLACE cons
1b790 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
1b7a0 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43  n are.** not. ^C
1b7b0 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
1b7c0 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63   that are interc
1b7d0 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44  epted by INSTEAD
1b7e0 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a   OF triggers .**
1b7f0 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
1b800 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73  ..** .** See als
1b810 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
1b820 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
1b830 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
1b840 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
1b850 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74  a], and the [tot
1b860 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c  al_changes() SQL
1b870 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
1b880 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
1b890 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
1b8a0 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
1b8b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1b8c0 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
1b8d0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1b8e0 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
1b8f0 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
1b900 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
1b910 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
1b920 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
1b930 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
1b940 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1b950 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1b960 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
1b970 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
1b980 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45  ning Query.** ME
1b990 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1b9a0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
1b9b0 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
1b9c0 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
1b9d0 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
1b9e0 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
1b9f0 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
1ba00 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
1ba10 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
1ba20 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
1ba30 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
1ba40 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
1ba50 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
1ba60 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
1ba70 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
1ba80 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
1ba90 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
1baa0 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
1bab0 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
1bac0 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
1bad0 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
1bae0 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
1baf0 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
1bb00 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
1bb10 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
1bb20 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
1bb30 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
1bb40 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
1bb50 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
1bb60 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
1bb70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1bb80 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
1bb90 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
1bba0 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
1bbb0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1bbc0 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
1bbd0 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
1bbe0 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
1bbf0 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
1bc00 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
1bc10 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
1bc20 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
1bc30 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
1bc40 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
1bc50 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
1bc60 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
1bc70 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
1bc80 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
1bc90 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
1bca0 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
1bcb0 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
1bcc0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
1bcd0 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
1bce0 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
1bcf0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
1bd00 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
1bd10 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
1bd20 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
1bd30 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
1bd40 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
1bd50 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
1bd60 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
1bd70 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
1bd80 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
1bd90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
1bda0 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
1bdb0 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
1bdc0 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
1bdd0 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
1bde0 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
1bdf0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1be00 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
1be10 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
1be20 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
1be30 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
1be40 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
1be50 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1be60 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
1be70 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
1be80 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
1be90 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
1bea0 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
1beb0 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
1bec0 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
1bed0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1bee0 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
1bef0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1bf00 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1bf10 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
1bf20 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
1bf30 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
1bf40 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
1bf50 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
1bf60 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1bf70 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
1bf80 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1bf90 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
1bfa0 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
1bfb0 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
1bfc0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
1bfd0 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
1bfe0 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
1bff0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1c000 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1c010 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
1c020 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
1c030 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76  ll returns..*/.v
1c040 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
1c050 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
1c060 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c070 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
1c080 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
1c090 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
1c0a0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1c0b0 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
1c0c0 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
1c0d0 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
1c0e0 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
1c0f0 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
1c100 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
1c110 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
1c120 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
1c130 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
1c140 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
1c150 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
1c160 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
1c170 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
1c180 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
1c190 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
1c1a0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1c1b0 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
1c1c0 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
1c1d0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
1c1e0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
1c1f0 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
1c200 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
1c210 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
1c220 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
1c230 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
1c240 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
1c250 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
1c260 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
1c270 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
1c280 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
1c290 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
1c2a0 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
1c2b0 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
1c2c0 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
1c2d0 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
1c2e0 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
1c2f0 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
1c300 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
1c310 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
1c320 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
1c330 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
1c340 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
1c350 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
1c360 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
1c370 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
1c380 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
1c390 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
1c3a0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1c3b0 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
1c3c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
1c3d0 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
1c3e0 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
1c3f0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
1c400 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
1c410 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
1c420 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1c430 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
1c440 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
1c450 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
1c460 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
1c470 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
1c480 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
1c490 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
1c4a0 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
1c4b0 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
1c4c0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
1c4d0 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
1c4e0 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
1c4f0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
1c500 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
1c510 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
1c520 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
1c530 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
1c540 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
1c550 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
1c560 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
1c570 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
1c580 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
1c590 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
1c5a0 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
1c5b0 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
1c5c0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1c5d0 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
1c5e0 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
1c5f0 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
1c600 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1c610 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
1c620 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1c630 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
1c640 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
1c650 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
1c660 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
1c670 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1c680 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
1c690 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
1c6a0 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
1c6b0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1c6c0 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
1c6d0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
1c6e0 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
1c6f0 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
1c700 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1c710 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
1c720 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
1c730 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
1c740 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73  * KEYWORDS: {bus
1c750 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
1c760 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65  ck} {busy handle
1c770 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
1c780 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
1c790 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1c7a0 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75  ndler(D,X,P) rou
1c7b0 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
1c7c0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a  back function X.
1c7d0 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  ** that might be
1c7e0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
1c7f0 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
1c800 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
1c810 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
1c820 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  s a database tab
1c830 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  le associated wi
1c840 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  th.** [database 
1c850 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68  connection] D wh
1c860 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  en another threa
1c870 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
1c880 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f  has the table lo
1c890 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  cked..** The sql
1c8a0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1c8b0 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  r() interface is
1c8c0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1c8d0 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nt.** [sqlite3_b
1c8e0 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61  usy_timeout()] a
1c8f0 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  nd [PRAGMA busy_
1c900 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20  timeout]..**.** 
1c910 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
1c920 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
1c930 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
1c940 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
1c950 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
1c960 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
1c970 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
1c980 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
1c990 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
1c9a0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
1c9b0 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
1c9c0 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
1c9d0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1c9e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1c9f0 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
1ca00 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
1ca10 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
1ca20 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
1ca30 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
1ca40 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
1ca50 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
1ca60 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1ca70 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
1ca80 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
1ca90 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
1caa0 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
1cab0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1cac0 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
1cad0 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20  oked previously 
1cae0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63  for the same loc
1caf0 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
1cb00 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
1cb10 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
1cb20 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
1cb30 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
1cb40 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
1cb50 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
1cb60 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
1cb70 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ] is returned.**
1cb80 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1cb90 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
1cba0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1cbb0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
1cbc0 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
1cbd0 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  ** is made to ac
1cbe0 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
1cbf0 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  e and the cycle 
1cc00 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
1cc10 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
1cc20 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
1cc30 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
1cc40 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
1cc50 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
1cc60 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
1cc70 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
1cc80 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
1cc90 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
1cca0 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
1ccb0 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
1ccc0 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
1ccd0 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
1cce0 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
1ccf0 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74  TE_BUSY].** to t
1cd00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
1cd10 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
1cd20 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20  ng the .** busy 
1cd30 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
1cd40 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
1cd50 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
1cd60 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
1cd70 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
1cd80 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
1cd90 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
1cda0 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
1cdb0 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
1cdc0 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
1cdd0 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
1cde0 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
1cdf0 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
1ce00 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
1ce10 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
1ce20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
1ce30 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
1ce40 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1ce50 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
1ce60 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
1ce70 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
1ce80 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
1ce90 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1cea0 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
1ceb0 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
1cec0 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
1ced0 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
1cee0 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
1cef0 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
1cf00 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
1cf10 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1cf20 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
1cf30 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
1cf40 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
1cf50 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
1cf60 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
1cf70 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
1cf80 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
1cf90 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
1cfa0 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
1cfb0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1cfc0 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
1cfd0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
1cfe0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1cff0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1d000 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
1d010 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
1d020 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1d030 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
1d040 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
1d050 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
1d060 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1d070 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
1d080 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
1d090 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1d0a0 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72  timeout()].** or
1d0b0 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41   evaluating [PRA
1d0c0 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1d0d0 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20  =N] will change 
1d0e0 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  the.** busy hand
1d0f0 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65  ler and thus cle
1d100 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c  ar any previousl
1d110 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c  y set busy handl
1d120 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
1d130 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
1d140 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
1d150 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
1d160 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
1d170 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1d180 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1d190 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
1d1a0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a  In other words,.
1d1b0 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1d1c0 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ler is not reent
1d1d0 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20  rant.  Any such 
1d1e0 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
1d1f0 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
1d200 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
1d210 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
1d220 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
1d230 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1d240 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
1d250 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1d260 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1d270 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
1d280 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1d290 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
1d2a0 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64  te3*,int(*)(void
1d2b0 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a  *,int),void*);..
1d2c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d2d0 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
1d2e0 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ut.** METHOD: sq
1d2f0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1d300 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
1d310 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1d320 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
1d330 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
1d340 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
1d350 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
1d360 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
1d370 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54  e is locked.  ^T
1d380 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
1d390 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
1d3a0 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
1d3b0 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
1d3c0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1d3d0 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
1d3e0 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65  umulated.  ^Afte
1d3f0 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  r at least "ms" 
1d400 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
1d410 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
1d420 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
1d430 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
1d440 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1d450 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
1d460 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a  QLITE_BUSY]..**.
1d470 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
1d480 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
1d490 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
1d4a0 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
1d4b0 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
1d4c0 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
1d4d0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
1d4e0 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1d4f0 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1d500 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
1d510 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1d520 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
1d530 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  t any given mome
1d540 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
1d550 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
1d560 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
1d570 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
1d580 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
1d590 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
1d5a0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
1d5b0 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
1d5c0 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
1d5d0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ed.)^.**.** See 
1d5e0 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62  also:  [PRAGMA b
1d5f0 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a  usy_timeout].*/.
1d600 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
1d610 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
1d620 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
1d630 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
1d640 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
1d650 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
1d660 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  eries.** METHOD:
1d670 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
1d680 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20  his is a legacy 
1d690 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69  interface that i
1d6a0 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20  s preserved for 
1d6b0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1d6c0 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20  ibility..** Use 
1d6d0 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
1d6e0 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65  e is not recomme
1d6f0 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69  nded..**.** Defi
1d700 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
1d710 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
1d720 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
1d730 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
1d740 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
1d750 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
1d760 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
1d770 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
1d780 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
1d790 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
1d7a0 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
1d7b0 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
1d7c0 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
1d7d0 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
1d7e0 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
1d7f0 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
1d800 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
1d810 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
1d820 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1d830 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
1d840 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
1d850 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
1d860 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
1d870 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
1d880 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
1d890 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1d8a0 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
1d8b0 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
1d8c0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
1d8d0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
1d8e0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
1d8f0 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
1d900 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
1d910 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
1d920 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
1d930 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
1d940 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1d950 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
1d960 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
1d970 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
1d980 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
1d990 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
1d9a0 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
1d9b0 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
1d9c0 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
1d9d0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
1d9e0 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
1d9f0 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
1da00 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
1da10 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
1da20 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
1da30 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1da40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
1da50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
1da60 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
1da70 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
1da80 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
1da90 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
1daa0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
1dab0 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
1dac0 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
1dad0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1dae0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1daf0 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
1db00 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
1db10 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1db20 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  le()]..**.** ^(A
1db30 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
1db40 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1db50 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
1db60 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
1db70 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
1db80 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1db90 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
1dba0 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
1dbb0 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
1dbc0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1dbd0 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
1dbe0 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
1dbf0 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
1dc00 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
1dc10 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
1dc20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
1dc30 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1dc40 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
1dc50 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
1dc60 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
1dc70 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
1dc80 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
1dc90 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
1dca0 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
1dcb0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
1dcc0 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
1dcd0 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
1dce0 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
1dcf0 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
1dd00 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
1dd10 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1dd20 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1dd30 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
1dd40 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1dd50 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
1dd60 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
1dd70 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
1dd80 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
1dd90 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1dda0 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
1ddb0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1ddc0 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
1ddd0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1dde0 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
1ddf0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1de00 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
1de10 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
1de20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
1de30 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
1de40 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1de50 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
1de60 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1de70 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
1de80 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
1de90 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
1dea0 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
1deb0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
1dec0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1ded0 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
1dee0 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
1def0 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  er and returns a
1df00 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
1df10 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
1df20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
1df30 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1df40 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c  * After the appl
1df50 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  ication has fini
1df60 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65  shed with the re
1df70 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65  sult from sqlite
1df80 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a  3_get_table(),.*
1df90 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74  * it must pass t
1dfa0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1dfb0 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
1dfc0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
1dfd0 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
1dfe0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1dff0 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
1e000 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
1e010 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
1e020 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1e030 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
1e040 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
1e050 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
1e060 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
1e070 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
1e080 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
1e090 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
1e0a0 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
1e0b0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
1e0c0 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
1e0d0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
1e0e0 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
1e0f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1e100 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1e110 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
1e120 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
1e130 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
1e140 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1e150 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
1e160 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
1e170 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
1e180 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
1e190 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
1e1a0 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
1e1b0 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
1e1c0 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
1e1d0 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
1e1e0 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
1e1f0 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
1e200 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
1e210 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
1e220 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
1e230 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
1e240 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
1e250 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
1e260 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
1e270 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
1e280 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1e290 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
1e2a0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
1e2b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
1e2c0 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
1e2d0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1e2e0 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
1e2f0 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
1e300 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1e310 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
1e320 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
1e330 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
1e340 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
1e350 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
1e360 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
1e370 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
1e380 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
1e390 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
1e3a0 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
1e3b0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1e3c0 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
1e3d0 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
1e3e0 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
1e3f0 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
1e400 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
1e410 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
1e420 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1e430 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
1e440 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e450 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
1e460 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
1e470 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
1e480 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1e490 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
1e4a0 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
1e4b0 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
1e4c0 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
1e4d0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1e4e0 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
1e4f0 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d  nes understand m
1e500 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f  ost of the commo
1e510 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e 67  n K&R formatting
1e520 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75   options,.** plu
1e530 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  s some additiona
1e540 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66  l non-standard f
1e550 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c 65 64  ormats, detailed
1e560 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20   below..** Note 
1e570 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74 68 65  that some of the
1e580 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20 66 6f   more obscure fo
1e590 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1e5a0 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20   from recent.** 
1e5b0 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e 64 61  C-library standa
1e5c0 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65 64 20  rds are omitted 
1e5d0 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d  from this implem
1e5e0 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  entation..**.** 
1e5f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
1e600 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
1e610 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
1e620 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
1e630 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
1e640 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
1e650 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
1e660 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
1e670 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1e680 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
1e690 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1e6a0 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
1e6b0 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
1e6c0 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
1e6d0 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
1e6e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1e6f0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1e700 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
1e710 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
1e720 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
1e730 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
1e740 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
1e750 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70  (The sqlite3_snp
1e760 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1e770 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
1e780 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
1e790 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
1e7a0 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
1e7b0 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
1e7c0 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
1e7d0 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
1e7e0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1e7f0 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
1e800 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
1e810 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1e820 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
1e830 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
1e840 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
1e850 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
1e860 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
1e870 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20  f().)^  This is 
1e880 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
1e890 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
1e8a0 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
1e8b0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
1e8c0 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
1e8d0 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e  patibility.  ^(N
1e8e0 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
1e8f0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1e900 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
1e910 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
1e920 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
1e930 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1e940 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
1e950 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
1e960 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20   the buffer.)^  
1e970 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
1e980 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1e990 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
1e9a0 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
1e9b0 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
1e9c0 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
1e9d0 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
1e9e0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1e9f0 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1ea00 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
1ea10 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
1ea20 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1ea30 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20  .** ^As long as 
1ea40 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
1ea50 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
1ea60 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
1ea70 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
1ea80 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
1ea90 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
1eaa0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1eab0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a  .  ^The first.**
1eac0 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
1ead0 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
1eae0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
1eaf0 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
1eb00 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
1eb10 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
1eb20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
1eb30 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
1eb40 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
1eb50 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
1eb60 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
1eb70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1eb80 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  vsnprintf() rout
1eb90 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73  ine is a varargs
1eba0 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69   version of sqli
1ebb0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a  te3_snprintf()..
1ebc0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1ebd0 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
1ebe0 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
1ebf0 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
1ec00 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
1ec10 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
1ec20 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
1ec30 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
1ec40 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
1ec50 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
1ec60 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
1ec70 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
1ec80 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
1ec90 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77 22 20  %q", "%Q", "%w" 
1eca0 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
1ecb0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
1ecc0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1ecd0 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
1ece0 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
1ecf0 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
1ed00 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
1ed10 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
1ed20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
1ed30 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
1ed40 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
1ed50 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
1ed60 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
1ed70 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
1ed80 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
1ed90 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
1eda0 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
1edb0 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
1edc0 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
1edd0 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
1ede0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
1edf0 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
1ee00 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
1ee10 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
1ee20 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
1ee30 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1ee40 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1ee50 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1ee60 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
1ee70 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
1ee80 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1ee90 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
1eea0 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
1eeb0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1eec0 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
1eed0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1eee0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1eef0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1ef00 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1ef10 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1ef20 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
1ef30 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1ef40 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1ef50 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1ef60 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1ef70 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1ef80 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
1ef90 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
1efa0 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
1efb0 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
1efc0 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
1efd0 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
1efe0 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
1eff0 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
1f000 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1f010 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1f020 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1f030 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
1f040 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
1f050 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1f060 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
1f070 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
1f080 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
1f090 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
1f0a0 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
1f0b0 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
1f0c0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
1f0d0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1f0e0 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1f0f0 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1f100 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
1f110 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
1f120 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1f130 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
1f140 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
1f150 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
1f160 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
1f170 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
1f180 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
1f190 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
1f1a0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
1f1b0 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
1f1c0 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
1f1d0 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
1f1e0 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
1f1f0 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
1f200 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
1f210 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
1f220 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
1f230 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
1f240 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
1f250 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
1f260 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
1f270 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
1f280 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
1f290 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
1f2a0 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
1f2b0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
1f2c0 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
1f2d0 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
1f2e0 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
1f2f0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1f300 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1f310 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1f320 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1f330 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
1f340 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1f350 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1f360 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1f370 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1f380 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1f390 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1f3a0 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
1f3b0 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
1f3c0 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
1f3d0 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
1f3e0 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
1f3f0 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
1f400 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
1f410 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
1f420 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69  he "%w" formatti
1f430 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b  ng option is lik
1f440 65 20 22 25 71 22 20 65 78 63 65 70 74 20 74 68  e "%q" except th
1f450 61 74 20 69 74 20 65 78 70 65 63 74 73 20 74 6f  at it expects to
1f460 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  .** be contained
1f470 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71   within double-q
1f480 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20 6f 66  uotes instead of
1f490 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20   single quotes, 
1f4a0 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61 70 65  and it.** escape
1f4b0 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f  s the double-quo
1f4c0 74 65 20 63 68 61 72 61 63 74 65 72 20 69 6e 73  te character ins
1f4d0 74 65 61 64 20 6f 66 20 74 68 65 20 73 69 6e 67  tead of the sing
1f4e0 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72  le-quote.** char
1f4f0 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20 22 25  acter.)^  The "%
1f500 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  w" formatting op
1f510 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65 64  tion is intended
1f520 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e 73 65   for safely inse
1f530 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61  rting.** table a
1f540 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20  nd column names 
1f550 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75 63 74  into a construct
1f560 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1f570 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
1f580 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
1f590 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1f5a0 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68  "%s" but with th
1f5b0 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
1f5c0 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
1f5d0 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
1f5e0 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
1f5f0 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
1f600 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1f610 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
1f620 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
1f630 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69  )^.*/.char *sqli
1f640 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
1f650 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68  t char*,...);.ch
1f660 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
1f670 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1f680 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72  , va_list);.char
1f690 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   *sqlite3_snprin
1f6a0 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1f6b0 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
1f6c0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73  char *sqlite3_vs
1f6d0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1f6e0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  *,const char*, v
1f6f0 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  a_list);../*.** 
1f700 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1f710 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
1f720 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
1f730 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
1f740 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
1f750 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
1f760 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
1f770 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
1f780 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
1f790 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
1f7a0 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
1f7b0 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
1f7c0 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
1f7d0 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
1f7e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
1f7f0 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
1f800 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
1f810 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1f820 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
1f830 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
1f840 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
1f850 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
1f860 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1f870 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
1f880 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
1f890 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
1f8a0 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
1f8b0 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
1f8c0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
1f8d0 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
1f8e0 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
1f8f0 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
1f900 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
1f910 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1f920 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
1f930 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
1f940 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
1f950 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
1f960 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
1f970 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
1f980 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1f990 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1f9a0 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72  e3_malloc64(N) r
1f9b0 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73  outine works jus
1f9c0 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  t like.** sqlite
1f9d0 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65  3_malloc(N) exce
1f9e0 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20  pt that N is an 
1f9f0 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20  unsigned 64-bit 
1fa00 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a  integer instead.
1fa10 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33  ** of a signed 3
1fa20 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a  2-bit integer..*
1fa30 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  *.** ^Calling sq
1fa40 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
1fa50 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
1fa60 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
1fa70 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
1fa80 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
1fa90 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
1faa0 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
1fab0 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
1fac0 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
1fad0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72   ^The sqlite3_fr
1fae0 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
1faf0 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
1fb00 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
1fb10 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
1fb20 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
1fb30 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
1fb40 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
1fb50 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
1fb60 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
1fb70 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
1fb80 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
1fb90 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
1fba0 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
1fbb0 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
1fbc0 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
1fbd0 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
1fbe0 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
1fbf0 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
1fc00 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
1fc10 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
1fc20 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
1fc30 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
1fc40 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
1fc50 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
1fc60 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
1fc70 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
1fc80 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
1fc90 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
1fca0 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
1fcb0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
1fcc0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  alloc()..**.** ^
1fcd0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
1fce0 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61  loc(X,N) interfa
1fcf0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
1fd00 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
1fd10 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1fd20 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65  on X to be at le
1fd30 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20  ast N bytes..** 
1fd40 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d 65  ^If the X parame
1fd50 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1fd60 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69  ealloc(X,N).** i
1fd70 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1fd80 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
1fd90 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
1fda0 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
1fdb0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e  lite3_malloc(N).
1fdc0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61  .** ^If the N pa
1fdd0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1fde0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1fdf0 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65  is zero or.** ne
1fe00 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20  gative then the 
1fe10 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63  behavior is exac
1fe20 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20  tly the same as 
1fe30 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1fe40 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e  e3_free(X)..** ^
1fe50 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1fe60 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70  X,N) returns a p
1fe70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
1fe80 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
1fe90 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
1fea0 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
1feb0 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63  NULL if insuffic
1fec0 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61  ient memory is a
1fed0 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
1fee0 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
1fef0 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
1ff00 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
1ff10 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
1ff20 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
1ff30 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
1ff40 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
1ff50 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
1ff60 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1ff70 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1ff80 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  N) and the prior
1ff90 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
1ffa0 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  reed..** ^If sql
1ffb0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1ffc0 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61  ) returns NULL a
1ffd0 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65  nd N is positive
1ffe0 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72  , then the.** pr
1fff0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
20000 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
20010 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
20020 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69  realloc64(X,N) i
20030 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20  nterfaces works 
20040 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73  the same as.** s
20050 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
20060 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  ,N) except that 
20070 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e  N is a 64-bit un
20080 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69  signed integer i
20090 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33  nstead.** of a 3
200a0 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  2-bit signed int
200b0 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  eger..**.** ^If 
200c0 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c  X is a memory al
200d0 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75  location previou
200e0 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
200f0 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
20100 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  (),.** sqlite3_m
20110 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74  alloc64(), sqlit
20120 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72  e3_realloc(), or
20130 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
20140 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  64(), then.** sq
20150 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72  lite3_msize(X) r
20160 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20  eturns the size 
20170 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61  of that memory a
20180 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74  llocation in byt
20190 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  es..** ^The valu
201a0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
201b0 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d  lite3_msize(X) m
201c0 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74  ight be larger t
201d0 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a  han the number.*
201e0 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 65  * of bytes reque
201f0 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 20  sted when X was 
20200 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20  allocated.  ^If 
20210 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  X is a NULL poin
20220 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ter then.** sqli
20230 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
20240 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58  urns zero.  If X
20250 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74   points to somet
20260 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74  hing that is not
20270 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  .** the beginnin
20280 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  g of memory allo
20290 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74  cation, or if it
202a0 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72   points to a for
202b0 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d  merly.** valid m
202c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
202d0 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65   that has now be
202e0 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74  en freed, then t
202f0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
20300 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  f sqlite3_msize(
20310 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  X) is undefined 
20320 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72  and possibly har
20330 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mful..**.** ^The
20340 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
20350 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
20360 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  oc(), sqlite3_re
20370 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
20380 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
20390 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
203a0 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c  loc64().** is al
203b0 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
203c0 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
203d0 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20  te boundary, or 
203e0 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62  to a.** 4 byte b
203f0 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b  oundary if the [
20400 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c  SQLITE_4_BYTE_AL
20410 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f  IGNED_MALLOC] co
20420 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
20430 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
20440 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
20450 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
20460 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
20470 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
20480 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
20490 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
204a0 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
204b0 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
204c0 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
204d0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
204e0 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
204f0 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
20500 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
20510 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
20520 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
20530 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
20540 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e  ors can be used.
20550 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20  .**.** Prior to 
20560 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
20570 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f  .7.10, the Windo
20580 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  ws OS interface 
20590 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20  layer called.** 
205a0 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
205b0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
205c0 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
205d0 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
205e0 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
205f0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
20600 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
20610 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
20620 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
20630 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
20640 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
20650 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
20660 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
20670 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65  cation errors we
20680 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
20690 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65  .** they were re
206a0 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b  ported back as [
206b0 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
206c0 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   or.** [SQLITE_I
206d0 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61  OERR] rather tha
206e0 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
206f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ..**.** The poin
20700 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ter arguments to
20710 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
20720 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
20730 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73  ealloc()].** mus
20740 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c  t be either NULL
20750 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72   or else pointer
20760 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
20770 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63  a prior.** invoc
20780 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
20790 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
207a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
207b0 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20  )] that have.** 
207c0 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c  not yet been rel
207d0 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eased..**.** The
207e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
207f0 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72  t not read or wr
20800 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a  ite any part of.
20810 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  ** a block of me
20820 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61  mory after it ha
20830 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20  s been released 
20840 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
20850 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
20860 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
20870 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
20880 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
20890 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
208a0 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75  lloc64(sqlite3_u
208b0 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71  int64);.void *sq
208c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
208d0 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
208e0 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
208f0 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  64(void*, sqlite
20900 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  3_uint64);.void 
20910 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
20920 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e  d*);.sqlite3_uin
20930 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  t64 sqlite3_msiz
20940 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
20950 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
20960 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
20970 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
20980 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
20990 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
209a0 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
209b0 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
209c0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
209d0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
209e0 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
209f0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
20a00 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
20a10 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
20a20 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
20a30 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
20a40 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
20a50 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
20a60 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
20a70 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
20a80 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
20a90 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
20aa0 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
20ab0 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
20ac0 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
20ad0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
20ae0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
20af0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
20b00 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
20b10 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
20b20 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
20b30 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
20b40 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
20b50 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
20b60 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
20b70 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
20b80 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
20b90 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
20ba0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
20bb0 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
20bc0 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
20bd0 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
20be0 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
20bf0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
20c00 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
20c10 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
20c20 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
20c30 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
20c40 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
20c50 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
20c60 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
20c70 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
20c80 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
20c90 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
20ca0 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
20cb0 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
20cc0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
20cd0 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
20ce0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
20cf0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
20d00 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
20d10 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
20d20 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
20d30 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
20d40 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
20d50 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
20d60 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
20d70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
20d80 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  t..*/.sqlite3_in
20d90 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
20da0 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73  ry_used(void);.s
20db0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
20dc0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
20dd0 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
20de0 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
20df0 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
20e00 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
20e10 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
20e20 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
20e30 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
20e40 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
20e50 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
20e60 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
20e70 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
20e80 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
20e90 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
20ea0 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
20eb0 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
20ec0 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
20ed0 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
20ee0 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
20ef0 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
20f00 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
20f10 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
20f20 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
20f30 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
20f40 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
20f50 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
20f60 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
20f70 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
20f80 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
20f90 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
20fa0 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
20fb0 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
20fc0 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
20fd0 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50  fer P..** ^The P
20fe0 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62   parameter can b
20ff0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
21000 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73  ..**.** ^If this
21010 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74   routine has not
21020 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79   been previously
21030 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68   called or if th
21040 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61  e previous.** ca
21050 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68  ll had N less th
21060 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c  an one or a NULL
21070 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20   pointer for P, 
21080 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73  then the PRNG is
21090 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67  .** seeded using
210a0 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
210b0 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52  ined from the xR
210c0 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64  andomness method
210d0 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75   of.** the defau
210e0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
210f0 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20   object..** ^If 
21100 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
21110 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
21120 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20  e had an N of 1 
21130 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a  or more and a.**
21140 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e   non-NULL P then
21150 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
21160 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
21170 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
21180 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
21190 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
211a0 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
211b0 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
211c0 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
211d0 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
211e0 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
211f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21200 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
21210 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
21220 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
21230 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45 59 57 4f  sqlite3.** KEYWO
21240 52 44 53 3a 20 7b 61 75 74 68 6f 72 69 7a 65 72  RDS: {authorizer
21250 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a   callback}.**.**
21260 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
21270 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
21280 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
21290 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
212a0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
212b0 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
212c0 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
212d0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
212e0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
212f0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
21300 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
21310 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
21320 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
21330 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
21340 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
21350 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
21360 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
21370 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
21380 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
21390 65 70 61 72 65 31 36 28 29 5d 2c 20 5b 73 71 6c  epare16()], [sql
213a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
213b0 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71  2()],.** and [sq
213c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
213d0 76 33 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69  v3()].  ^At vari
213e0 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
213f0 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
21400 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
21410 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
21420 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
21430 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
21440 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
21450 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
21460 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
21470 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
21480 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
21490 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  .  ^The authoriz
214a0 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
214b0 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
214c0 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
214d0 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
214e0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
214f0 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
21500 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
21510 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
21520 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
21530 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
21540 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
21550 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
21560 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
21570 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
21580 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
21590 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
215a0 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
215b0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
215c0 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
215d0 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
215e0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
215f0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
21600 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
21610 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
21620 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
21630 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
21640 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
21650 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
21660 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
21670 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
21680 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
21690 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
216a0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
216b0 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
216c0 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
216d0 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e  uested is ok.  ^
216e0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
216f0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
21700 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
21710 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21720 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
21730 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
21740 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
21750 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
21760 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
21770 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
21780 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
21790 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
217a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
217b0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
217c0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
217d0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
217e0 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
217f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
21800 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
21810 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
21820 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e  face. ^The secon
21830 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
21840 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
21850 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
21860 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
21870 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
21880 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
21890 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
218a0 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
218b0 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68  d. ^The third th
218c0 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
218d0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
218e0 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 65 69   callback are ei
218f0 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ther NULL pointe
21900 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65 72 6d 69  rs or zero-termi
21910 6e 61 74 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a  nated strings.**
21920 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
21930 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73  ditional details
21940 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
21950 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
21960 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  ed..** Applicati
21970 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61 79 73 20  ons must always 
21980 62 65 20 70 72 65 70 61 72 65 64 20 74 6f 20 65  be prepared to e
21990 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55 4c 4c 20  ncounter a NULL 
219a0 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e 79 0a 2a  pointer in any.*
219b0 2a 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 74  * of the third t
219c0 68 72 6f 75 67 68 20 74 68 65 20 73 69 78 74 68  hrough the sixth
219d0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
219e0 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
219f0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
21a00 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
21a10 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
21a20 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
21a30 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
21a40 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
21a50 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
21a60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21a70 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
21a80 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
21a90 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
21aa0 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
21ab0 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
21ac0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
21ad0 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
21ae0 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
21af0 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
21b00 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
21b10 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
21b20 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
21b30 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
21b40 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
21b50 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
21b60 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
21b70 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e 20  table..** ^When 
21b80 61 20 74 61 62 6c 65 20 69 73 20 72 65 66 65 72  a table is refer
21b90 65 6e 63 65 64 20 62 79 20 61 20 5b 53 45 4c 45  enced by a [SELE
21ba0 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f 6c 75 6d  CT] but no colum
21bb0 6e 20 76 61 6c 75 65 73 20 61 72 65 0a 2a 2a 20  n values are.** 
21bc0 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 20 74  extracted from t
21bd0 68 61 74 20 74 61 62 6c 65 20 28 66 6f 72 20 65  hat table (for e
21be0 78 61 6d 70 6c 65 20 69 6e 20 61 20 71 75 65 72  xample in a quer
21bf0 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c 45 43  y like.** "SELEC
21c00 54 20 63 6f 75 6e 74 28 2a 29 20 46 52 4f 4d 20  T count(*) FROM 
21c10 74 61 62 22 29 20 74 68 65 6e 20 74 68 65 20 5b  tab") then the [
21c20 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 75 74  SQLITE_READ] aut
21c30 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21c40 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  .** is invoked o
21c50 6e 63 65 20 66 6f 72 20 74 68 61 74 20 74 61 62  nce for that tab
21c60 6c 65 20 77 69 74 68 20 61 20 63 6f 6c 75 6d 6e  le with a column
21c70 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 61 6e   name that is an
21c80 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a   empty string..*
21c90 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
21ca0 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
21cb0 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
21cc0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
21cd0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
21ce0 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
21cf0 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
21d00 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
21d10 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
21d20 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
21d30 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
21d40 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
21d50 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
21d60 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
21d70 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
21d80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21d90 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
21da0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
21db0 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
21dc0 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
21dd0 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
21de0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
21df0 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
21e00 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
21e10 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
21e20 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
21e30 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
21e40 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
21e50 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
21e60 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
21e70 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
21e80 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
21e90 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
21ea0 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
21eb0 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
21ec0 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
21ed0 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
21ee0 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
21ef0 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
21f00 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
21f10 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
21f20 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
21f30 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
21f40 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
21f50 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
21f60 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
21f70 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
21f80 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
21f90 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
21fa0 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
21fb0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
21fc0 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
21fd0 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
21fe0 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
21ff0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
22000 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
22010 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
22020 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
22030 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
22040 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
22050 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
22060 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
22070 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
22080 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
22090 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
220a0 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
220b0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
220c0 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
220d0 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
220e0 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
220f0 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73  **.** ^(Only a s
22100 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
22110 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
22120 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
22130 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
22140 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
22150 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
22160 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
22170 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
22180 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20  evious call.)^  
22190 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74  ^Disable the aut
221a0 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
221b0 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
221c0 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
221d0 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
221e0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
221f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
22200 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
22210 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
22220 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
22230 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
22240 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
22250 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
22260 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
22270 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
22280 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
22290 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
222a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
222b0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
222c0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
222d0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
222e0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
222f0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
22300 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57  agraph..**.** ^W
22310 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
22320 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73  pare_v2()] is us
22330 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
22340 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
22350 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
22360 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64  t be re-prepared
22370 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
22380 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
22390 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
223a0 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
223b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
223c0 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
223d0 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
223e0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
223f0 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
22400 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
22410 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
22420 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
22430 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
22440 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
22450 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
22460 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
22470 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
22480 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
22490 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
224a0 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
224b0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
224c0 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
224d0 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
224e0 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
224f0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
22500 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
22510 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
22520 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
22530 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65  epare_v2() to re
22540 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
22550 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
22560 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e  ma change..*/.in
22570 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
22580 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
22590 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
225a0 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
225b0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
225c0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
225d0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
225e0 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
225f0 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
22600 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
22610 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a  r Return Codes.*
22620 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
22630 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
22640 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
22650 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
22660 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
22670 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
22680 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
22690 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
226a0 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
226b0 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
226c0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
226d0 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
226e0 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
226f0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
22700 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
22710 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
22720 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
22730 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
22740 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ion..**.** Note 
22750 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f  that SQLITE_IGNO
22760 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  RE is also used 
22770 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72  as a [conflict r
22780 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a  esolution mode].
22790 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ** returned from
227a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74   the [sqlite3_vt
227b0 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
227c0 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
227d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
227e0 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
227f0 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
22800 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
22810 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
22820 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
22830 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
22840 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
22850 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
22860 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
22870 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
22880 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
22890 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
228a0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
228b0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
228c0 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
228d0 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
228e0 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
228f0 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
22900 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
22910 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
22920 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
22930 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
22940 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
22950 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
22960 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
22970 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
22980 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
22990 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
229a0 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
229b0 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
229c0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
229d0 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
229e0 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
229f0 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
22a00 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
22a10 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
22a20 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
22a30 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
22a40 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
22a50 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
22a60 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
22a70 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
22a80 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
22a90 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
22aa0 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
22ab0 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
22ac0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
22ad0 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
22ae0 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
22af0 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
22b00 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
22b10 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
22b20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
22b30 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
22b40 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
22b50 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
22b60 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
22b70 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
22b80 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
22b90 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
22ba0 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
22bb0 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
22bc0 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
22bd0 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
22be0 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
22bf0 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
22c00 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
22c10 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
22c20 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
22c30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22c40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22c50 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
22c60 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
22c70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
22c80 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
22c90 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
22ca0 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
22cb0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
22cc0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
22cd0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
22ce0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
22cf0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22d00 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22d10 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22d20 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
22d30 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
22d40 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
22d50 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
22d60 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22d70 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
22d80 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
22d90 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22da0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22db0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22dc0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
22dd0 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
22de0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
22df0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
22e00 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22e10 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
22e20 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
22e30 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
22e40 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22e50 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22e60 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
22e70 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
22e80 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
22e90 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22ea0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22eb0 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
22ec0 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
22ed0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
22ee0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22ef0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22f00 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
22f10 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
22f20 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
22f30 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22f40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22f50 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
22f60 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
22f70 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
22f80 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22f90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22fa0 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
22fb0 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
22fc0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
22fd0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22fe0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22ff0 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
23000 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
23010 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
23020 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
23030 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
23040 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
23050 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
23060 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
23070 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
23080 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
23090 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
230a0 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
230b0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
230c0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
230d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
230e0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
230f0 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
23100 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
23110 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
23120 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
23130 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
23140 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
23150 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
23160 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
23170 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
23180 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
23190 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
231a0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
231b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
231c0 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
231d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
231e0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
231f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
23200 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
23210 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
23220 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
23230 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
23240 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
23250 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
23260 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
23270 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
23280 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
23290 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
232a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
232b0 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
232c0 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
232d0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
232e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
232f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23300 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
23310 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
23320 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
23330 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
23340 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23350 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
23360 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
23370 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
23380 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
23390 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
233a0 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
233b0 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
233c0 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
233d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
233e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
233f0 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
23400 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
23410 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
23420 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
23430 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23440 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
23450 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
23460 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
23470 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
23480 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23490 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
234a0 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
234b0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
234c0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
234d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
234e0 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
234f0 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
23500 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
23510 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
23520 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
23530 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
23540 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
23550 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
23560 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
23570 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
23580 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
23590 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
235a0 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
235b0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
235c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
235d0 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
235e0 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
235f0 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
23600 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
23610 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
23620 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
23630 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
23640 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
23650 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
23660 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
23670 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23680 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
23690 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
236a0 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56   SQLITE_RECURSIV
236b0 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20  E            33 
236c0 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
236d0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
236e0 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43       */../*.** C
236f0 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
23700 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
23710 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48  unctions.** METH
23720 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
23730 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
23740 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e   are deprecated.
23750 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
23760 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e  3_trace_v2()] in
23770 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65  terface.** inste
23780 61 64 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e  ad of the routin
23790 65 73 20 64 65 73 63 72 69 62 65 64 20 68 65 72  es described her
237a0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e..**.** These r
237b0 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
237c0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
237d0 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
237e0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
237f0 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
23800 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
23810 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
23820 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  s..**.** ^The ca
23830 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
23840 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
23850 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
23860 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
23870 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
23880 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
23890 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
238a0 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
238b0 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
238c0 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
238d0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
238e0 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65   with a UTF-8 re
238f0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a  ndering of the.*
23900 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
23910 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74  text as the stat
23920 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
23930 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  ns executing..**
23940 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71   ^(Additional sq
23950 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
23960 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63  llbacks might oc
23970 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
23980 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
23990 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
239a0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
239b0 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
239c0 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
239d0 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
239e0 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
239f0 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  rigger.)^.**.** 
23a00 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  The [SQLITE_TRAC
23a10 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f  E_SIZE_LIMIT] co
23a20 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
23a30 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
23a40 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65   limit.** the le
23a50 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70  ngth of [bound p
23a60 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73  arameter] expans
23a70 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75  ion in the outpu
23a80 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61  t of sqlite3_tra
23a90 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ce()..**.** ^The
23aa0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
23ab0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
23ac0 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
23ad0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
23ae0 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
23af0 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
23b00 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
23b10 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
23b20 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
23b30 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
23b40 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
23b50 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
23b60 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
23b70 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
23b80 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e   took to run.  ^
23b90 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
23ba0 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20  back.** time is 
23bb0 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f  in units of nano
23bc0 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72  seconds, however
23bd0 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
23be0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
23bf0 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f  s only capable o
23c00 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65  f millisecond re
23c10 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20  solution so the 
23c20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66  six least signif
23c30 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20  icant.** digits 
23c40 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20  in the time are 
23c50 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75  meaningless.  Fu
23c60 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
23c70 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74   SQLite.** might
23c80 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72   provide greater
23c90 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74   resolution on t
23ca0 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c  he profiler call
23cb0 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71  back.  The.** sq
23cc0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
23cd0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73  function is cons
23ce0 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
23cf0 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75  tal and is.** su
23d00 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
23d10 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
23d20 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
23d30 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
23d40 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  ED void *sqlite3
23d50 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
23d60 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 61 63 65  .   void(*xTrace
23d70 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
23d80 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
23d90 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
23da0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
23db0 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
23dc0 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
23dd0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
23de0 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
23df0 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
23e00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
23e10 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20 43  QL Trace Event C
23e20 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
23e30 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a  : SQLITE_TRACE.*
23e40 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
23e50 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63 6c  ants identify cl
23e60 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73 20  asses of events 
23e70 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69  that can be moni
23e80 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74  tored.** using t
23e90 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  he [sqlite3_trac
23ea0 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67 20  e_v2()] tracing 
23eb0 6c 6f 67 69 63 2e 20 20 54 68 65 20 74 68 69 72  logic.  The thir
23ec0 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  d argument.** to
23ed0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
23ee0 76 32 28 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65  v2()] is an OR-e
23ef0 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  d combination of
23f00 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a   one or more of.
23f10 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
23f20 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68   constants.  ^Th
23f30 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
23f40 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61   to the trace ca
23f50 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65  llback.** is one
23f60 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
23f70 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a  g constants..**.
23f80 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67 20 63  ** New tracing c
23f90 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20  onstants may be 
23fa0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
23fb0 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
23fc0 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ^A trace callbac
23fd0 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67 75 6d  k has four argum
23fe0 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28  ents: xCallback(
23ff0 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68  T,C,P,X)..** ^Th
24000 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e T argument is 
24010 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74 65 67  one of the integ
24020 65 72 20 74 79 70 65 20 63 6f 64 65 73 20 61 62  er type codes ab
24030 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61  ove..** ^The C a
24040 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70  rgument is a cop
24050 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74  y of the context
24060 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
24070 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  in as the.** fou
24080 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
24090 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
240a0 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61  2()]..** The P a
240b0 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61  nd X arguments a
240c0 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73  re pointers whos
240d0 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e  e meanings depen
240e0 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64  d on T..**.** <d
240f0 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  l>.** [[SQLITE_T
24100 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e  RACE_STMT]] <dt>
24110 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
24120 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  T</dt>.** <dd>^A
24130 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53  n SQLITE_TRACE_S
24140 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  TMT callback is 
24150 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 70  invoked when a p
24160 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24170 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67 69 6e  t.** first begin
24180 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f  s running and po
24190 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65 72 20  ssibly at other 
241a0 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74 68 65  times during the
241b0 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  .** execution of
241c0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
241d0 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20 61 73  atement, such as
241e0 20 61 74 20 74 68 65 20 73 74 61 72 74 20 6f 66   at the start of
241f0 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67 65 72   each.** trigger
24200 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68   subprogram. ^Th
24210 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
24220 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
24230 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
24240 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58  atement]. ^The X
24250 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
24260 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
24270 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  ng which.** is t
24280 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20 53 51  he unexpanded SQ
24290 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20 70 72  L text of the pr
242a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
242b0 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65   or an SQL comme
242c0 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69  nt .** that indi
242d0 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f 63 61  cates the invoca
242e0 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67 67 65  tion of a trigge
242f0 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  r.  ^The callbac
24300 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a  k can compute.**
24310 20 74 68 65 20 73 61 6d 65 20 74 65 78 74 20 74   the same text t
24320 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 20 62  hat would have b
24330 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  een returned by 
24340 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
24350 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a 20  te3_trace()].** 
24360 69 6e 74 65 72 66 61 63 65 20 62 79 20 75 73 69  interface by usi
24370 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e  ng the X argumen
24380 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e 73 20  t when X begins 
24390 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20 69 6e  with "--" and in
243a0 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  voking.** [sqlit
243b0 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
243c0 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  P)] otherwise..*
243d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  *.** [[SQLITE_TR
243e0 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c 64  ACE_PROFILE]] <d
243f0 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  t>SQLITE_TRACE_P
24400 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ROFILE</dt>.** <
24410 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
24420 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c  ACE_PROFILE call
24430 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20 61 70  back provides ap
24440 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68 65 20  proximately the 
24450 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  same.** informat
24460 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76 69 64  ion as is provid
24470 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
24480 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63 61  e3_profile()] ca
24490 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20  llback..** ^The 
244a0 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
244b0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
244c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
244d0 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58  nt] and the.** X
244e0 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
244f0 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69 6e 74   to a 64-bit int
24500 65 67 65 72 20 77 68 69 63 68 20 69 73 20 74 68  eger which is th
24510 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66 0a 2a  e estimated of.*
24520 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
24530 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74 20  nanosecond that 
24540 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
24550 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
24560 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49  un..** ^The SQLI
24570 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
24580 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
24590 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 73 74  oked when the st
245a0 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
245b0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
245c0 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 74  _TRACE_ROW]] <dt
245d0 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f  >SQLITE_TRACE_RO
245e0 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  W</dt>.** <dd>^A
245f0 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  n SQLITE_TRACE_R
24600 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  OW callback is i
24610 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
24620 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
24630 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 74 65  atement generate
24640 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  s a single row o
24650 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e  f result.  .** ^
24660 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
24670 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
24680 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
24690 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a  tement] and the.
246a0 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73  ** X argument is
246b0 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   unused..**.** [
246c0 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c  [SQLITE_TRACE_CL
246d0 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  OSE]] <dt>SQLITE
246e0 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 74  _TRACE_CLOSE</dt
246f0 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
24700 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20  ITE_TRACE_CLOSE 
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 20 61 20 64 61 74 61 62  ked when a datab
24730 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
24740 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68  n closes..** ^Th
24750 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
24760 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
24770 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
24780 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a  ction] object.**
24790 20 61 6e 64 20 74 68 65 20 58 20 61 72 67 75 6d   and the X argum
247a0 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a  ent is unused..*
247b0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
247c0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
247d0 53 54 4d 54 20 20 20 20 20 20 20 30 78 30 31 0a  STMT       0x01.
247e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
247f0 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20 20 20  RACE_PROFILE    
24800 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x02.#define SQL
24810 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 20 20  ITE_TRACE_ROW   
24820 20 20 20 20 20 30 78 30 34 0a 23 64 65 66 69 6e       0x04.#defin
24830 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  e SQLITE_TRACE_C
24840 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38 0a 0a  LOSE      0x08..
24850 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24860 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a 2a  SQL Trace Hook.*
24870 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
24880 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
24890 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c  ite3_trace_v2(D,
248a0 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  M,X,P) interface
248b0 20 72 65 67 69 73 74 65 72 73 20 61 20 74 72 61   registers a tra
248c0 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  ce callback.** f
248d0 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69 6e 73  unction X agains
248e0 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  t [database conn
248f0 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e 67  ection] D, using
24900 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b 20 4d   property mask M
24910 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74 20  .** and context 
24920 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49 66 20  pointer P.  ^If 
24930 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69  the X callback i
24940 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 20  s.** NULL or if 
24950 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a 65  the M mask is ze
24960 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69 6e 67  ro, then tracing
24970 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 54   is disabled.  T
24980 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e 74  he.** M argument
24990 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 62   should be the b
249a0 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63 6f 6d  itwise OR-ed com
249b0 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a  bination of.** z
249c0 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c  ero or more [SQL
249d0 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73 74  ITE_TRACE] const
249e0 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  ants..**.** ^Eac
249f0 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  h call to either
24a00 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
24a10 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63   or sqlite3_trac
24a20 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64 65 73  e_v2() overrides
24a30 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20 61   .** (cancels) a
24a40 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74  ny prior calls t
24a50 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  o sqlite3_trace(
24a60 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61  ) or sqlite3_tra
24a70 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  ce_v2()..**.** ^
24a80 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69  The X callback i
24a90 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  s invoked whenev
24aa0 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20 65 76  er any of the ev
24ab0 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65 64 20  ents identified 
24ac0 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63  by .** mask M oc
24ad0 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74 65 67  cur.  ^The integ
24ae0 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  er return value 
24af0 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61 63  from the callbac
24b00 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a  k is currently.*
24b10 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67  * ignored, thoug
24b20 68 20 74 68 69 73 20 6d 61 79 20 63 68 61 6e 67  h this may chang
24b30 65 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  e in future rele
24b40 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a  ases.  Callback.
24b50 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
24b60 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ns should return
24b70 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72 65 20   zero to ensure 
24b80 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69 62 69  future compatibi
24b90 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74  lity..**.** ^A t
24ba0 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  race callback is
24bb0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 6f   invoked with fo
24bc0 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 63 61  ur arguments: ca
24bd0 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e  llback(T,C,P,X).
24be0 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d  .** ^The T argum
24bf0 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ent is one of th
24c00 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d  e [SQLITE_TRACE]
24c10 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f  .** constants to
24c20 20 69 6e 64 69 63 61 74 65 20 77 68 79 20 74 68   indicate why th
24c30 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 20 69  e callback was i
24c40 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  nvoked..** ^The 
24c50 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  C argument is a 
24c60 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
24c70 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ext pointer..** 
24c80 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75  The P and X argu
24c90 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65  ments are pointe
24ca0 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67  rs whose meaning
24cb0 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a  s depend on T..*
24cc0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
24cd0 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e 74 65  _trace_v2() inte
24ce0 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65  rface is intende
24cf0 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74 68 65  d to replace the
24d00 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
24d10 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 74  faces [sqlite3_t
24d20 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  race()] and [sql
24d30 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c  ite3_profile()],
24d40 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68 0a 2a   both of which.*
24d50 2a 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64  * are deprecated
24d60 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
24d70 5f 74 72 61 63 65 5f 76 32 28 0a 20 20 73 71 6c  _trace_v2(.  sql
24d80 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65  ite3*,.  unsigne
24d90 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a  d uMask,.  int(*
24da0 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67  xCallback)(unsig
24db0 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c  ned,void*,void*,
24dc0 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  void*),.  void *
24dd0 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pCtx.);../*.** C
24de0 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
24df0 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
24e00 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
24e10 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
24e20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
24e30 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50  _handler(D,N,X,P
24e40 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
24e50 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
24e60 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f  ** function X to
24e70 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   be invoked peri
24e80 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
24e90 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c  long running cal
24ea0 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
24eb0 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
24ec0 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20  te3_step()] and 
24ed0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
24ee0 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74  le()] for.** dat
24ef0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24f00 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20   D.  An example 
24f10 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
24f20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
24f30 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
24f40 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
24f50 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  e query..**.** ^
24f60 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20  The parameter P 
24f70 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
24f80 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  h as the only pa
24f90 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a  rameter to the .
24fa0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
24fb0 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61  tion X.  ^The pa
24fc0 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65  rameter N is the
24fd0 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d   approximate num
24fe0 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74  ber of .** [virt
24ff0 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74  ual machine inst
25000 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61  ructions] that a
25010 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74  re evaluated bet
25020 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a  ween successive.
25030 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
25040 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58  f the callback X
25050 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73  .  ^If N is less
25060 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74   than one then t
25070 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68  he progress.** h
25080 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c  andler is disabl
25090 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  ed..**.** ^Only 
250a0 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73  a single progres
250b0 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65  s handler may be
250c0 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20   defined at one 
250d0 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74  time per.** [dat
250e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
250f0 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77  ]; setting a new
25100 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
25110 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a  r cancels the.**
25120 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74   old one.  ^Sett
25130 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20  ing parameter X 
25140 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73  to NULL disables
25150 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
25160 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70  ndler..** ^The p
25170 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
25180 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64  is also disabled
25190 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f   by setting N to
251a0 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a   a value less.**
251b0 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e   than 1..**.** ^
251c0 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
251d0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
251e0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
251f0 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
25200 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
25210 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
25220 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
25230 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
25240 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
25250 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
25260 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
25270 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
25280 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
25290 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
252a0 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
252b0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
252c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
252d0 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67  invoked the prog
252e0 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
252f0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
25300 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
25310 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
25320 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
25330 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
25340 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
25350 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
25360 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
25370 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
25380 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  **.*/.void sqlit
25390 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
253a0 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
253b0 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
253c0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
253d0 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
253e0 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
253f0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e Connection.** 
25400 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c  CONSTRUCTOR: sql
25410 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ite3.**.** ^Thes
25420 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
25430 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
25440 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69  se file as speci
25450 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
25460 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
25470 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
25480 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
25490 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
254a0 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
254b0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
254c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
254d0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
254e0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
254f0 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
25500 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
25510 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
25520 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
25530 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
25540 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
25550 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
25560 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
25570 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
25580 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
25590 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
255a0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
255b0 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
255c0 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
255d0 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
255e0 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
255f0 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
25600 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
25610 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
25620 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
25630 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
25640 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
25650 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
25660 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
25670 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
25680 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
25690 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
256a0 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
256b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
256c0 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
256d0 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
256e0 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
256f0 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
25700 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
25710 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
25720 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
25730 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
25740 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
25750 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
25760 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
25770 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
25780 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55  coding will be U
25790 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73  TF-8 for databas
257a0 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  es created using
257b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
257c0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
257d0 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64  en_v2().  ^The d
257e0 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
257f0 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a  for databases.**
25800 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73   created using s
25810 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
25820 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69  will be UTF-16 i
25830 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
25840 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57  e order..**.** W
25850 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
25860 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
25870 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
25880 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
25890 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
258a0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
258b0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
258c0 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
258d0 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
258e0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
258f0 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
25900 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
25910 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
25920 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
25930 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
25940 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
25950 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
25960 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
25970 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
25980 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
25990 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
259a0 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
259b0 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
259c0 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c  ction.  ^(The fl
259d0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
259e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
259f0 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f  _v2() can take o
25a00 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  ne of.** the fol
25a10 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c  lowing three val
25a20 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  ues, optionally 
25a30 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68  combined with th
25a40 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  e .** [SQLITE_OP
25a50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
25a60 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
25a70 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
25a80 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c  EN_SHAREDCACHE],
25a90 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
25aa0 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20  _PRIVATECACHE], 
25ab0 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  and/or [SQLITE_O
25ac0 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29  PEN_URI] flags:)
25ad0 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ^.**.** <dl>.** 
25ae0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
25af0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
25b00 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
25b10 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
25b20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
25b30 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
25b40 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
25b50 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
25b60 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
25b70 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
25b80 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
25b90 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c  OPEN_READWRITE]<
25ba0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
25bb0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
25bc0 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
25bd0 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
25be0 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
25bf0 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68  ng.** only if th
25c00 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
25c10 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
25c20 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
25c30 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a  m.  In either.**
25c40 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
25c50 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20  se must already 
25c60 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65  exist, otherwise
25c70 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
25c80 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
25c90 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
25ca0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
25cb0 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
25cc0 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
25cd0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
25ce0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
25cf0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
25d00 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
25d10 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65  ted if.** it doe
25d20 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  s not already ex
25d30 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65  ist. This is the
25d40 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69   behavior that i
25d50 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f  s always used fo
25d60 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
25d70 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
25d80 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e  open16().</dd>)^
25d90 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
25da0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
25db0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
25dc0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
25dd0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
25de0 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
25df0 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c  n above optional
25e00 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
25e10 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54   other.** [SQLIT
25e20 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
25e30 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20  | SQLITE_OPEN_* 
25e40 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  bits].** then th
25e50 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
25e60 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
25e70 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  If the [SQLITE_O
25e80 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
25e90 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74  g is set, then t
25ea0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
25eb0 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20  ection.** opens 
25ec0 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72  in the multi-thr
25ed0 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
25ee0 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20  ode] as long as 
25ef0 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  the single-threa
25f00 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f  d.** mode has no
25f10 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f  t been set at co
25f20 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
25f30 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74  art-time.  ^If t
25f40 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
25f50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
25f60 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74  ag is set then t
25f70 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
25f80 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20  ection opens.** 
25f90 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  in the serialize
25fa0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
25fb0 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65  e] unless single
25fc0 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70  -thread was.** p
25fd0 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74  reviously select
25fe0 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ed at compile-ti
25ff0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
26000 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
26010 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
26020 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
26030 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
26040 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  nection to be.**
26050 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65   eligible to use
26060 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
26070 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73  ode], regardless
26080 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
26090 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ot shared.** cac
260a0 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73  he is enabled us
260b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  ing [sqlite3_ena
260c0 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
260d0 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53  ()].  ^The.** [S
260e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
260f0 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  TECACHE] flag ca
26100 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
26110 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
26120 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61  not.** participa
26130 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61  te in [shared ca
26140 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69  che mode] even i
26150 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e  f it is enabled.
26160 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
26170 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
26180 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26190 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ) is the name of
261a0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
261b0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  _vfs] object tha
261c0 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70  t defines the op
261d0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
261e0 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a  nterface that.**
261f0 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
26200 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
26210 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68  uld use.  ^If th
26220 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
26230 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
26240 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
26250 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
26260 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
26270 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   used..**.** ^If
26280 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
26290 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
262a0 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
262b0 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
262c0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
262d0 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
262e0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68  connection.  ^Th
262f0 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  is in-memory dat
26300 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
26310 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61  h when.** the da
26320 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26330 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75  n is closed.  Fu
26340 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
26350 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
26360 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
26370 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
26380 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62  filenames that b
26390 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
263a0 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  " character..** 
263b0 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  It is recommende
263c0 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61  d that when a da
263d0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
263e0 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65  actually does be
263f0 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a  gin with.** a ":
26400 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20  " character you 
26410 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68  should prefix th
26420 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
26430 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20  a pathname such 
26440 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76  as.** "./" to av
26450 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a  oid ambiguity..*
26460 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
26470 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
26480 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
26490 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
264a0 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
264b0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
264c0 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20  created.  ^This 
264d0 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
264e0 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
264f0 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
26500 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
26510 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
26520 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
26530 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
26540 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33  names in sqlite3
26550 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52  _open()]] <h3>UR
26560 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e  I Filenames</h3>
26570 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20  .**.** ^If [URI 
26580 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70  filename] interp
26590 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
265a0 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c  led, and the fil
265b0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
265c0 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66  * begins with "f
265d0 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20  ile:", then the 
265e0 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65  filename is inte
265f0 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49  rpreted as a URI
26600 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61  . ^URI.** filena
26610 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
26620 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  n is enabled if 
26630 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
26640 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a  _URI] flag is.**
26650 20 73 65 74 20 69 6e 20 74 68 65 20 74 68 69 72   set in the thir
26660 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
26670 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c  lite3_open_v2(),
26680 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a   or if it has.**
26690 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c   been enabled gl
266a0 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65  obally using the
266b0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
266c0 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68  URI] option with
266d0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
266e0 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f  _config()] metho
266f0 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c  d or by the [SQL
26700 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d  ITE_USE_URI] com
26710 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
26720 2e 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  ..** URI filenam
26730 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
26740 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a   is turned off.*
26750 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75  * by default, bu
26760 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  t future release
26770 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
26780 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c  t enable URI fil
26790 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72  ename.** interpr
267a0 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75  etation by defau
267b0 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66  lt.  See "[URI f
267c0 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61  ilenames]" for a
267d0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
267e0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
267f0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  URI filenames ar
26800 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69  e parsed accordi
26810 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20  ng to RFC 3986. 
26820 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74  ^If the URI cont
26830 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f  ains an.** autho
26840 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75  rity, then it mu
26850 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20  st be either an 
26860 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
26870 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22  the string .** "
26880 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20  localhost". ^If 
26890 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73  the authority is
268a0 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74   not an empty st
268b0 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f  ring or "localho
268c0 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f  st", an .** erro
268d0 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f  r is returned to
268e0 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68   the caller. ^Th
268f0 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f  e fragment compo
26900 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69  nent of a URI, i
26910 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69  f .** present, i
26920 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
26930 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
26940 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74  e path component
26950 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74   of the URI as t
26960 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
26970 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63  isk file.** whic
26980 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  h contains the d
26990 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65  atabase. ^If the
269a0 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74   path begins wit
269b0 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65  h a '/' characte
269c0 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  r, .** then it i
269d0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
269e0 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
269f0 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  h. ^If the path 
26a00 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a  does not begin .
26a10 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d  ** with a '/' (m
26a20 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20  eaning that the 
26a30 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f  authority sectio
26a40 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  n is omitted fro
26a50 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68  m the URI).** th
26a60 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69  en the path is i
26a70 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
26a80 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a  relative path. .
26a90 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c  ** ^(On windows,
26aa0 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f   the first compo
26ab0 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c  nent of an absol
26ac0 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20  ute path .** is 
26ad0 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63  a drive specific
26ae0 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22  ation (e.g. "C:"
26af0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72  ).)^.**.** [[cor
26b00 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61  e URI query para
26b10 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20  meters]].** The 
26b20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
26b30 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e  of a URI may con
26b40 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tain parameters 
26b50 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72  that are interpr
26b60 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62  eted.** either b
26b70 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c  y SQLite itself,
26b80 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20   or by a [VFS | 
26b90 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65  custom VFS imple
26ba0 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53  mentation]..** S
26bb0 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75  QLite and its bu
26bc0 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69  ilt-in [VFSes] i
26bd0 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20  nterpret the.** 
26be0 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20  following query 
26bf0 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a  parameters:.**.*
26c00 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e  * <ul>.**   <li>
26c10 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68   <b>vfs</b>: ^Th
26c20 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65  e "vfs" paramete
26c30 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  r may be used to
26c40 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d   specify the nam
26c50 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46  e of.**     a VF
26c60 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72  S object that pr
26c70 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61  ovides the opera
26c80 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
26c90 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c  rface that shoul
26ca0 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64  d.**     be used
26cb0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
26cc0 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20  atabase file on 
26cd0 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f  disk. ^If this o
26ce0 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a  ption is set to.
26cf0 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20  **     an empty 
26d00 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75  string the defau
26d10 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73  lt VFS object is
26d20 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69   used. ^Specifyi
26d30 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a  ng an unknown.**
26d40 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65       VFS is an e
26d50 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65  rror. ^If sqlite
26d60 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
26d70 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20  sed and the vfs 
26d80 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
26d90 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74   present, then t
26da0 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64  he VFS specified
26db0 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74   by the option t
26dc0 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20  akes precedence 
26dd0 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20  over.**     the 
26de0 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
26df0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
26e00 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
26e10 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
26e20 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c     <li> <b>mode<
26e30 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20  /b>: ^(The mode 
26e40 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
26e50 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
26e60 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20  ro", "rw",.**   
26e70 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d    "rwc", or "mem
26e80 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67  ory". Attempting
26e90 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e   to set it to an
26ea0 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73  y other value is
26eb0 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72  .**     an error
26ec0 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20  )^. .**     ^If 
26ed0 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65  "ro" is specifie
26ee0 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  d, then the data
26ef0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
26f00 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a  or read-only .**
26f10 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73       access, jus
26f20 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c  t as if the [SQL
26f30 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
26f40 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e  Y] flag had been
26f50 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20   set in the .** 
26f60 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65      third argume
26f70 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
26f80 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65  en_v2(). ^If the
26f90 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20   mode option is 
26fa0 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22  set to .**     "
26fb0 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61  rw", then the da
26fc0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
26fd0 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20   for read-write 
26fe0 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29  (but not create)
26ff0 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
27000 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50   as if SQLITE_OP
27010 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75  EN_READWRITE (bu
27020 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45  t not SQLITE_OPE
27030 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a  N_CREATE) had .*
27040 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20  *     been set. 
27050 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20  ^Value "rwc" is 
27060 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
27070 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20  tting both .**  
27080 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52     SQLITE_OPEN_R
27090 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c  EADWRITE and SQL
270a0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e  ITE_OPEN_CREATE.
270b0 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f    ^If the mode o
270c0 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
270d0 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20  set to "memory" 
270e0 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d  then a pure [in-
270f0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d  memory database]
27100 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64   that never read
27110 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74  s.**     or writ
27120 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20  es from disk is 
27130 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20  used. ^It is an 
27140 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79  error to specify
27150 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20   a value for.** 
27160 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72      the mode par
27170 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c  ameter that is l
27180 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20  ess restrictive 
27190 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66  than that specif
271a0 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68  ied by.**     th
271b0 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69  e flags passed i
271c0 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
271d0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
271e0 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
271f0 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68  *   <li> <b>cach
27200 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68  e</b>: ^The cach
27210 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
27220 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
27230 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20   "shared" or.** 
27240 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e      "private". ^
27250 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73  Setting it to "s
27260 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61  hared" is equiva
27270 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
27280 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  the.**     SQLIT
27290 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
272a0 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c  HE bit in the fl
272b0 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ags argument pas
272c0 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71  sed to.**     sq
272d0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
272e0 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61   ^Setting the ca
272f0 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  che parameter to
27300 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a   "private" is .*
27310 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74  *     equivalent
27320 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20   to setting the 
27330 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
27340 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a  ATECACHE bit..**
27350 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33       ^If sqlite3
27360 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
27370 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68  ed and the "cach
27380 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e" parameter is 
27390 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20  present in.**   
273a0 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65    a URI filename
273b0 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72  , its value over
273c0 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69  rides any behavi
273d0 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20  or requested by 
273e0 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53  setting.**     S
273f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
27400 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54  TECACHE or SQLIT
27410 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
27420 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20  HE flag..**.**  
27430 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e  <li> <b>psow</b>
27440 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61  : ^The psow para
27450 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20  meter indicates 
27460 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
27470 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72  he.**     [power
27480 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20  safe overwrite] 
27490 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72  property does or
274a0 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20   does not apply 
274b0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74  to the.**     st
274c0 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77  orage media on w
274d0 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73  hich the databas
274e0 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a  e file resides..
274f0 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e  **.**  <li> <b>n
27500 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20  olock</b>: ^The 
27510 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72  nolock parameter
27520 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
27530 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ery parameter.**
27540 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65       which if se
27550 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20  t disables file 
27560 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62  locking in rollb
27570 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65  ack journal mode
27580 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20  s.  This.**     
27590 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63  is useful for ac
275a0 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61  cessing a databa
275b0 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74  se on a filesyst
275c0 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  em that does not
275d0 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20  .**     support 
275e0 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f  locking.  Cautio
275f0 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72  n:  Database cor
27600 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ruption might re
27610 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20  sult if two.**  
27620 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65     or more proce
27630 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68  sses write to th
27640 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
27650 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74  and any one of t
27660 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63  hose.**     proc
27670 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63  esses uses noloc
27680 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  k=1..**.**  <li>
27690 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62   <b>immutable</b
276a0 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c  >: ^The immutabl
276b0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  e parameter is a
276c0 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a   boolean query.*
276d0 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20  *     parameter 
276e0 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74  that indicates t
276f0 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
27700 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20   file is stored 
27710 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f  on.**     read-o
27720 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65  nly media.  ^Whe
27730 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73  n immutable is s
27740 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d  et, SQLite assum
27750 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20  es that the.**  
27760 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65     database file
27770 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
27780 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72  ed, even by a pr
27790 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65  ocess with highe
277a0 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65  r.**     privile
277b0 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64  ge, and so the d
277c0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
277d0 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20  d read-only and 
277e0 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20  all locking.**  
277f0 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65     and change de
27800 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62  tection is disab
27810 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53  led.  Caution: S
27820 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74  etting the immut
27830 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70  able.**     prop
27840 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61  erty on a databa
27850 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65  se file that doe
27860 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65  s in fact change
27870 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20   can result.**  
27880 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20     in incorrect 
27890 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e  query results an
278a0 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52  d/or [SQLITE_COR
278b0 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a  RUPT] errors..**
278c0 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b       See also: [
278d0 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
278e0 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20  UTABLE]..**     
278f0 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a    .** </ul>.**.*
27900 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  * ^Specifying an
27910 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74   unknown paramet
27920 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  er in the query 
27930 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
27940 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20  RI is not an.** 
27950 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76  error.  Future v
27960 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
27970 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61  e might understa
27980 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75  nd additional qu
27990 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
279a0 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20  s.  See "[query 
279b0 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20  parameters with 
279c0 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20  special meaning 
279d0 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a  to SQLite]" for.
279e0 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
279f0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
27a00 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20   [[URI filename 
27a10 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55  examples]] <h3>U
27a20 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
27a30 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ples</h3>.**.** 
27a40 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
27a50 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63  " align=center c
27a60 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a  ellpadding=5>.**
27a70 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69   <tr><th> URI fi
27a80 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73  lenames <th> Res
27a90 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ults.** <tr><td>
27aa0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74   file:data.db <t
27ab0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
27ac0 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
27ad0 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
27ae0 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
27af0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
27b00 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
27b10 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20  ta.db<br>.**    
27b20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f        file:///ho
27b30 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
27b40 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <br> .**        
27b50 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f    file://localho
27b60 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  st/home/fred/dat
27b70 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a  a.db <br> <td> .
27b80 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
27b90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
27ba0 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
27bb0 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e  ata.db"..** <tr>
27bc0 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b  <td> file://dark
27bd0 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  star/home/fred/d
27be0 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
27bf0 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
27c00 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73  r. "darkstar" is
27c10 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65   not a recognize
27c20 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20  d authority..** 
27c30 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77  <tr><td style="w
27c40 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61  hite-space:nowra
27c50 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  p"> .**         
27c60 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75   file:///C:/Docu
27c70 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65  ments%20and%20Se
27c80 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b  ttings/fred/Desk
27c90 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20  top/data.db.**  
27ca0 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20     <td> Windows 
27cb0 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66  only: Open the f
27cc0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e  ile "data.db" on
27cd0 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20   fred's desktop 
27ce0 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20  on drive.**     
27cf0 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68       C:. Note th
27d00 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70  at the %20 escap
27d10 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d  ing in this exam
27d20 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63  ple is not stric
27d30 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  tly .**         
27d40 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61   necessary - spa
27d50 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61  ce characters ca
27d60 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61  n be used litera
27d70 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lly.**          
27d80 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  in URI filenames
27d90 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
27da0 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
27db0 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65  ro&cache=private
27dc0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
27dd0 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61     Open file "da
27de0 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
27df0 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20  rrent directory 
27e00 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63  for read-only ac
27e10 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20  cess..**        
27e20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20    Regardless of 
27e30 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
27e40 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65  hared-cache mode
27e50 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a   is enabled by.*
27e60 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
27e70 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74  lt, use a privat
27e80 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e  e cache..** <tr>
27e90 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
27ea0 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73  fred/data.db?vfs
27eb0 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74  =unix-dotfile <t
27ec0 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
27ed0 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
27ee0 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
27ef0 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
27f00 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65  FS "unix-dotfile
27f10 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ".**          th
27f20 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65  at uses dot-file
27f30 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f  s in place of po
27f40 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63  six advisory loc
27f50 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  king..** <tr><td
27f60 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
27f70 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64  ode=readonly <td
27f80 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
27f90 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e  n error. "readon
27fa0 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c  ly" is not a val
27fb0 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68  id option for th
27fc0 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74  e "mode" paramet
27fd0 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  er..** </table>.
27fe0 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64  **.** ^URI hexad
27ff0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
28000 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72  quences (%HH) ar
28010 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  e supported with
28020 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a  in the path and.
28030 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  ** query compone
28040 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20  nts of a URI. A 
28050 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
28060 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73  pe sequence cons
28070 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72  ists of a.** per
28080 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20  cent sign - "%" 
28090 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78  - followed by ex
280a0 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65  actly two hexade
280b0 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a  cimal digits .**
280c0 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f   specifying an o
280d0 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66  ctet value. ^Bef
280e0 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20  ore the path or 
280f0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
28100 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c   of a.** URI fil
28110 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70  ename are interp
28120 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20  reted, they are 
28130 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
28140 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20  F-8 and all .** 
28150 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
28160 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70  pe sequences rep
28170 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c  laced by a singl
28180 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e  e byte containin
28190 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70  g the.** corresp
281a0 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66  onding octet. If
281b0 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65   this process ge
281c0 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c  nerates an inval
281d0 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  id UTF-8 encodin
281e0 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  g,.** the result
281f0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
28200 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
28210 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
28220 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
28230 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
28240 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
28250 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
28260 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
28270 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
28280 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
28290 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
282a0 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
282b0 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
282c0 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
282d0 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
282e0 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
282f0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
28300 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
28310 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
28320 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
28330 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
28340 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
28350 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
28360 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
28370 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
28380 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
28390 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
283a0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
283b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
283c0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
283d0 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  2().  Otherwise,
283e0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
283f0 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
28400 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
28410 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
28420 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   fail..**.** See
28430 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
28440 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a  temp_directory].
28450 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
28460 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
28470 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
28480 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
28490 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
284a0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
284b0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
284c0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
284d0 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
284e0 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
284f0 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
28500 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
28510 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
28520 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
28530 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
28540 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
28550 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
28560 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
28570 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
28580 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
28590 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
285a0 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
285b0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
285c0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
285d0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
285e0 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
285f0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
28600 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
28610 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
28620 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
28630 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
28640 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
28650 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
28660 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50  Values For URI P
28670 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
28680 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74  These are utilit
28690 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66  y routines, usef
286a0 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d  ul to VFS implem
286b0 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20  entations, that 
286c0 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20  check.** to see 
286d0 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69  if a database fi
286e0 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61  le was a URI tha
286f0 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70  t contained a sp
28700 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a  ecific query .**
28710 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20   parameter, and 
28720 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68  if so obtains th
28730 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
28740 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e  query parameter.
28750 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74  .**.** If F is t
28760 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
28770 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
28780 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
28790 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a  en() method of .
287a0 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65  ** a VFS impleme
287b0 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  ntation when the
287c0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
287d0 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20   to xOpen() has 
287e0 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20  one or .** more 
287f0 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  of the [SQLITE_O
28800 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c  PEN_URI] or [SQL
28810 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
28820 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a  ] bits set and.*
28830 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20  * P is the name 
28840 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
28850 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ameter, then.** 
28860 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
28870 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
28880 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
28890 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74  the P.** paramet
288a0 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20  er if it exists 
288b0 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
288c0 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20  r if P does not 
288d0 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20  appear as a .** 
288e0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
288f0 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61  on F.  If P is a
28900 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
28910 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20   of F.** has no 
28920 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20  explicit value, 
28930 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
28940 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
28950 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69  returns.** a poi
28960 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79  nter to an empty
28970 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
28980 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
28990 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
289a0 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68  utine assumes th
289b0 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61  at P is a boolea
289c0 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61  n.** parameter a
289d0 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  nd returns true 
289e0 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29  (1) or false (0)
289f0 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68   according to th
28a00 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e  e value.** of P.
28a10 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72    The sqlite3_ur
28a20 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
28a30 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
28a40 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65   true (1) if the
28a50 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65  .** value of que
28a60 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
28a70 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20  s one of "yes", 
28a80 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20  "true", or "on" 
28a90 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f  in any.** case o
28aa0 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  r if the value b
28ab0 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e  egins with a non
28ac0 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54  -zero number.  T
28ad0 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  he .** sqlite3_u
28ae0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
28af0 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  ) routines retur
28b00 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20  ns false (0) if 
28b10 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
28b20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
28b30 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22  P is one of "no"
28b40 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f  , "false", or "o
28b50 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20  ff" in any case 
28b60 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c  or.** if the val
28b70 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
28b80 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20   numeric zero.  
28b90 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75  If P is not a qu
28ba0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
28bb0 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20   on F or if the 
28bc0 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f  value of P is do
28bd0 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79  es not match any
28be0 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65   of the.** above
28bf0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
28c00 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
28c10 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29  ) returns (B!=0)
28c20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
28c30 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c  te3_uri_int64(F,
28c40 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e  P,D) routine con
28c50 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20  verts the value 
28c60 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36  of P into a.** 6
28c70 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
28c80 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eger and returns
28c90 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f   that integer, o
28ca0 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  r D if P does no
28cb0 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20  t.** exist.  If 
28cc0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
28cd0 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  s something othe
28ce0 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65  r than an intege
28cf0 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20  r, then.** zero 
28d00 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
28d10 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55  .** If F is a NU
28d20 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
28d30 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
28d40 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
28d50 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20  rns NULL and.** 
28d60 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
28d70 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
28d80 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e  ns B.  If F is n
28d90 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ot a NULL pointe
28da0 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20  r and.** is not 
28db0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
28dc0 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72  pathname pointer
28dd0 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73   that SQLite pas
28de0 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
28df0 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64  en.** VFS method
28e00 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
28e10 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
28e20 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
28e30 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a   and probably.**
28e40 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
28e50 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
28e60 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
28e70 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
28e80 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
28e90 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69  char *zParam);.i
28ea0 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  nt sqlite3_uri_b
28eb0 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61  oolean(const cha
28ec0 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20  r *zFile, const 
28ed0 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e  char *zParam, in
28ee0 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c  t bDefault);.sql
28ef0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
28f00 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e  e3_uri_int64(con
28f10 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20  st char*, const 
28f20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  char*, sqlite3_i
28f30 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt64);.../*.** C
28f40 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
28f50 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
28f60 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
28f70 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ite3.**.** ^If t
28f80 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73  he most recent s
28f90 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
28fa0 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  l associated wit
28fb0 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  h .** [database 
28fc0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61  connection] D fa
28fd0 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73  iled, then the s
28fe0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44  qlite3_errcode(D
28ff0 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  ) interface.** r
29000 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
29010 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
29020 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65   or [extended re
29030 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
29040 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e  hat.** API call.
29050 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20  .** If the most 
29060 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
29070 77 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a  was successful,.
29080 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
29090 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
290a0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
290b0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
290c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
290d0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
290e0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
290f0 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
29100 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
29110 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
29120 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
29130 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
29140 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
29150 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
29160 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  sabled..**.** ^T
29170 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
29180 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
29190 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
291a0 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
291b0 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
291c0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
291d0 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
291e0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
291f0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
29200 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
29210 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
29220 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
29230 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
29240 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
29250 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
29260 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74  d to worry about
29270 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73   freeing the res
29280 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ult..** However,
29290 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
292a0 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77  g might be overw
292b0 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
292c0 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73  cated by.** subs
292d0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
292e0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
292f0 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73  erface functions
29300 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
29310 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20  qlite3_errstr() 
29320 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
29330 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61  s the English-la
29340 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74  nguage text.** t
29350 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
29360 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c  e [result code],
29370 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28   as UTF-8..** ^(
29380 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
29390 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
293a0 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
293b0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  ed internally.**
293c0 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65   and must not be
293d0 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70   freed by the ap
293e0 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a  plication)^..**.
293f0 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69  ** When the seri
29400 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
29410 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73  g mode] is in us
29420 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  e, it might be t
29430 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20  he.** case that 
29440 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f  a second error o
29450 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72  ccurs on a separ
29460 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65  ate thread in be
29470 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d  tween.** the tim
29480 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65  e of the first e
29490 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c  rror and the cal
294a0 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  l to these inter
294b0 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  faces..** When t
294c0 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65  hat happens, the
294d0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69   second error wi
294e0 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73  ll be reported s
294f0 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e  ince these.** in
29500 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20  terfaces always 
29510 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20  report the most 
29520 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20  recent result.  
29530 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73  To avoid.** this
29540 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61  , each thread ca
29550 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69  n obtain exclusi
29560 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  ve use of the [d
29570 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29580 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f  on] D.** by invo
29590 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
295a0 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69  tex_enter]([sqli
295b0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
295c0 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69  ) before beginni
295d0 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61  ng.** to use D a
295e0 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  nd invoking [sql
295f0 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
29600 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
29610 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a  tex](D)) after.*
29620 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74  * all calls to t
29630 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69  he interfaces li
29640 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f  sted here are co
29650 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mpleted..**.** I
29660 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
29670 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
29680 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
29690 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
296a0 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
296b0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
296c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
296d0 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
296e0 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
296f0 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
29700 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
29710 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  set..*/.int sqli
29720 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
29730 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71  te3 *db);.int sq
29740 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
29750 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
29760 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  db);.const char 
29770 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
29780 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
29790 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
297a0 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
297b0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
297c0 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e  qlite3_errstr(in
297d0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
297e0 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74  REF: Prepared St
297f0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
29800 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
29810 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
29820 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
29830 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
29840 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
29850 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
29860 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
29870 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a  statement that.*
29880 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69  * has been compi
29890 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20  led into binary 
298a0 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64  form and is read
298b0 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  y to be evaluate
298c0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f  d..**.** Think o
298d0 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  f each SQL state
298e0 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61  ment as a separa
298f0 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67  te computer prog
29900 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69  ram.  The.** ori
29910 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69  ginal SQL text i
29920 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
29930 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  A prepared state
29940 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20  ment object .** 
29950 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20  is the compiled 
29960 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c  object code.  Al
29970 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f  l SQL must be co
29980 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a  nverted into a.*
29990 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
299a0 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63  ment before it c
299b0 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  an be run..**.**
299c0 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20   The life-cycle 
299d0 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74  of a prepared st
299e0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
299f0 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65  sually goes like
29a00 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
29a10 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
29a20 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
29a30 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
29a40 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
29a50 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  epare_v2()]..** 
29a60 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
29a70 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d   to [parameters]
29a80 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
29a90 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
29aa0 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
29ab0 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
29ac0 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
29ad0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
29ae0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
29af0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
29b00 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
29b10 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
29b20 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
29b30 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
29b40 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
29b50 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
29b60 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
29b70 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
29b80 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
29b90 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
29ba0 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  )]..** </ol>.*/.
29bb0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
29bc0 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
29bd0 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
29be0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
29bf0 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45  ime Limits.** ME
29c00 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
29c10 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
29c20 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
29c30 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
29c40 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
29c50 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
29c60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
29c70 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
29c80 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
29c90 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
29ca0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
29cb0 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
29cc0 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
29cd0 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
29ce0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
29cf0 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
29d00 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
29d10 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
29d20 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
29d30 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
29d40 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
29d50 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
29d60 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
29d70 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
29d80 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a  construct.)^.**.
29d90 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
29da0 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
29db0 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
29dc0 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
29dd0 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68  d..** ^(For each
29de0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
29df0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e  SQLITE_LIMIT_<i>
29e00 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69  NAME</i> there i
29e10 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
29e20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
29e30 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f  nd].** set at co
29e40 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20  mpile-time by a 
29e50 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
29e60 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b  acro called.** [
29e70 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
29e80 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d  MAX_<i>NAME</i>]
29e90 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
29ea0 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
29eb0 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
29ec0 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
29ed0 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
29ee0 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
29ef0 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
29f00 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
29f10 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
29f20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
29f30 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e  r bound..**.** ^
29f40 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
29f50 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
29f60 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67   limit was chang
29f70 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ed, the .** [sql
29f80 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  ite3_limit()] in
29f90 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
29fa0 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
29fb0 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a  of the limit..**
29fc0 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64   ^Hence, to find
29fd0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
29fe0 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69  ue of a limit wi
29ff0 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69  thout changing i
2a000 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76  t,.** simply inv
2a010 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61  oke this interfa
2a020 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72  ce with the thir
2a030 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
2a040 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  to -1..**.** Run
2a050 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
2a060 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
2a070 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
2a080 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
2a090 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
2a0a0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
2a0b0 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
2a0c0 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
2a0d0 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
2a0e0 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
2a0f0 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
2a100 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
2a110 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
2a120 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
2a130 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
2a140 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
2a150 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
2a160 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
2a170 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
2a180 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
2a190 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
2a1a0 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
2a1b0 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
2a1c0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
2a1d0 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
2a1e0 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
2a1f0 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
2a200 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
2a210 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
2a220 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
2a230 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
2a240 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
2a250 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
2a260 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
2a270 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
2a280 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
2a290 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
2a2a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
2a2b0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
2a2c0 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
2a2d0 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
2a2e0 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
2a2f0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
2a300 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
2a310 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
2a320 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
2a330 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
2a340 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
2a350 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
2a360 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
2a370 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
2a380 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
2a390 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
2a3a0 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73  leases..*/.int s
2a3b0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
2a3c0 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
2a3d0 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
2a3e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
2a3f0 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
2a400 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  gories.** KEYWOR
2a410 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
2a420 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74  ory} {*limit cat
2a430 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54  egories}.**.** T
2a440 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
2a450 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65  efine various pe
2a460 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73  rformance limits
2a470 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
2a480 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74  lowered at run-t
2a490 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ime using [sqlit
2a4a0 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20  e3_limit()]..** 
2a4b0 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20  The synopsis of 
2a4c0 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  the meanings of 
2a4d0 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69  the various limi
2a4e0 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f  ts is shown belo
2a4f0 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  w..** Additional
2a500 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
2a510 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69  available at [li
2a520 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e  mits | Limits in
2a530 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20   SQLite]..**.** 
2a540 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
2a550 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20  _LIMIT_LENGTH]] 
2a560 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2a570 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
2a580 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2a590 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
2a5a0 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
2a5b0 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79  table row, in by
2a5c0 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  tes.<dd>)^.**.**
2a5d0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2a5e0 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  SQL_LENGTH]] ^(<
2a5f0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2a600 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
2a610 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2a620 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
2a630 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69  SQL statement, i
2a640 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a  n bytes.</dd>)^.
2a650 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2a660 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28  IMIT_COLUMN]] ^(
2a670 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2a680 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
2a690 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2a6a0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2a6b0 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
2a6c0 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
2a6d0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
2a6e0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
2a6f0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
2a700 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2a710 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
2a720 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
2a730 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
2a740 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  se.</dd>)^.**.**
2a750 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2a760 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  EXPR_DEPTH]] ^(<
2a770 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2a780 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
2a790 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2a7a0 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
2a7b0 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
2a7c0 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
2a7d0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2a7e0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
2a7f0 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64  ND_SELECT]] ^(<d
2a800 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
2a810 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
2a820 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2a830 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2a840 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
2a850 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
2a860 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
2a870 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2a880 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c  IT_VDBE_OP]] ^(<
2a890 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2a8a0 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20  VDBE_OP</dt>.** 
2a8b0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2a8c0 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75  number of instru
2a8d0 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74  ctions in a virt
2a8e0 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67  ual machine prog
2a8f0 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69  ram.** used to i
2a900 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20  mplement an SQL 
2a910 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 5b  statement.  If [
2a920 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2a930 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 74 68 65 20  v2()] or.** the 
2a940 65 71 75 69 76 61 6c 65 6e 74 20 74 72 69 65 73  equivalent tries
2a950 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 73 70 61   to allocate spa
2a960 63 65 20 66 6f 72 20 6d 6f 72 65 20 74 68 61 6e  ce for more than
2a970 20 74 68 69 73 20 6d 61 6e 79 20 6f 70 63 6f 64   this many opcod
2a980 65 73 0a 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c  es.** in a singl
2a990 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2a9a0 6d 65 6e 74 2c 20 61 6e 20 53 51 4c 49 54 45 5f  ment, an SQLITE_
2a9b0 4e 4f 4d 45 4d 20 65 72 72 6f 72 20 69 73 20 72  NOMEM error is r
2a9c0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
2a9d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2a9e0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
2a9f0 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  G]] ^(<dt>SQLITE
2aa00 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
2aa10 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
2aa20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
2aa30 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2aa40 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
2aa50 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2aa60 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
2aa70 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  HED]] ^(<dt>SQLI
2aa80 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
2aa90 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
2aaa0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2aab0 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
2aac0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
2aad0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
2aae0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
2aaf0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
2ab00 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  TH]].** ^(<dt>SQ
2ab10 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
2ab20 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
2ab30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2ab40 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2ab50 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
2ab60 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
2ab70 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
2ab80 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
2ab90 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2aba0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
2abb0 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c  _NUMBER]].** ^(<
2abc0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2abd0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
2abe0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2abf0 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
2ac00 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
2ac10 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
2ac20 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
2ac30 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2ac40 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
2ac50 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
2ac60 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
2ac70 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
2ac80 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
2ac90 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
2aca0 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
2acb0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2acc0 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
2acd0 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74  _THREADS]] ^(<dt
2ace0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f  >SQLITE_LIMIT_WO
2acf0 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74  RKER_THREADS</dt
2ad00 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2ad10 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
2ad20 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20  uxiliary worker 
2ad30 74 68 72 65 61 64 73 20 74 68 61 74 20 61 20 73  threads that a s
2ad40 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72  ingle.** [prepar
2ad50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61  ed statement] ma
2ad60 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a  y start.</dd>)^.
2ad70 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
2ad80 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2ad90 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
2ada0 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
2adb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2adc0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
2add0 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
2ade0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2adf0 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
2ae00 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
2ae10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2ae20 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
2ae30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
2ae40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2ae50 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
2ae60 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
2ae70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2ae80 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
2ae90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2aea0 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
2aeb0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
2aec0 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
2aed0 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
2aee0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
2aef0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2af00 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
2af10 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
2af20 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
2af30 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
2af40 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
2af50 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
2af60 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
2af70 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
2af80 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  ER_DEPTH        
2af90 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
2afa0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
2afb0 45 52 5f 54 48 52 45 41 44 53 20 20 20 20 20 20  ER_THREADS      
2afc0 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43       11../*.** C
2afd0 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65  API3REF: Prepare
2afe0 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Flags.**.** The
2aff0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
2b000 69 6e 65 20 76 61 72 69 6f 75 73 20 66 6c 61 67  ine various flag
2b010 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 61  s that can be pa
2b020 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 22 70 72  ssed into.** "pr
2b030 65 70 46 6c 61 67 73 22 20 70 61 72 61 6d 65 74  epFlags" paramet
2b040 65 72 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  er of the [sqlit
2b050 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
2b060 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2b070 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
2b080 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 0a   interfaces..**.
2b090 2a 2a 20 4e 65 77 20 66 6c 61 67 73 20 6d 61 79  ** New flags may
2b0a0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
2b0b0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
2b0c0 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64  SQLite..**.** <d
2b0d0 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50  l>.** [[SQLITE_P
2b0e0 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e  REPARE_PERSISTEN
2b0f0 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
2b100 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54  _PREPARE_PERSIST
2b110 45 4e 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ENT</dt>.** <dd>
2b120 54 68 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41  The SQLITE_PREPA
2b130 52 45 5f 50 45 52 53 49 53 54 45 4e 54 20 66 6c  RE_PERSISTENT fl
2b140 61 67 20 69 73 20 61 20 68 69 6e 74 20 74 6f 20  ag is a hint to 
2b150 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65  the query planne
2b160 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
2b170 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b180 20 77 69 6c 6c 20 62 65 20 72 65 74 61 69 6e 65   will be retaine
2b190 64 20 66 6f 72 20 61 20 6c 6f 6e 67 20 74 69 6d  d for a long tim
2b1a0 65 20 61 6e 64 0a 2a 2a 20 70 72 6f 62 61 62 6c  e and.** probabl
2b1b0 79 20 72 65 75 73 65 64 20 6d 61 6e 79 20 74 69  y reused many ti
2b1c0 6d 65 73 2e 29 5e 20 5e 57 69 74 68 6f 75 74 20  mes.)^ ^Without 
2b1d0 74 68 69 73 20 66 6c 61 67 2c 20 5b 73 71 6c 69  this flag, [sqli
2b1e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2b1f0 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2b200 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2b210 5d 20 61 73 73 75 6d 65 20 74 68 61 74 20 74 68  ] assume that th
2b220 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2b230 6d 65 6e 74 20 77 69 6c 6c 20 0a 2a 2a 20 62 65  ment will .** be
2b240 20 75 73 65 64 20 6a 75 73 74 20 6f 6e 63 65 20   used just once 
2b250 6f 72 20 61 74 20 6d 6f 73 74 20 61 20 66 65 77  or at most a few
2b260 20 74 69 6d 65 73 20 61 6e 64 20 74 68 65 6e 20   times and then 
2b270 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67 0a  destroyed using.
2b280 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2b290 6c 69 7a 65 28 29 5d 20 72 65 6c 61 74 69 76 65  lize()] relative
2b2a0 6c 79 20 73 6f 6f 6e 2e 20 54 68 65 20 63 75 72  ly soon. The cur
2b2b0 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
2b2c0 69 6f 6e 20 61 63 74 73 0a 2a 2a 20 6f 6e 20 74  ion acts.** on t
2b2d0 68 69 73 20 68 69 6e 74 20 62 79 20 61 76 6f 69  his hint by avoi
2b2e0 64 69 6e 67 20 74 68 65 20 75 73 65 20 6f 66 20  ding the use of 
2b2f0 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
2b300 79 5d 20 73 6f 20 61 73 20 6e 6f 74 20 74 6f 0a  y] so as not to.
2b310 2a 2a 20 64 65 70 6c 65 74 65 20 74 68 65 20 6c  ** deplete the l
2b320 69 6d 69 74 65 64 20 73 74 6f 72 65 20 6f 66 20  imited store of 
2b330 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
2b340 2e 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e  . Future version
2b350 73 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  s of.** SQLite m
2b360 61 79 20 61 63 74 20 6f 6e 20 74 68 69 73 20 68  ay act on this h
2b370 69 6e 74 20 64 69 66 66 65 72 65 6e 74 6c 79 2e  int differently.
2b380 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
2b390 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 45 50  fine SQLITE_PREP
2b3a0 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 20 20  ARE_PERSISTENT  
2b3b0 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 31              0x01
2b3c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b3d0 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
2b3e0 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
2b3f0 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
2b400 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
2b410 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
2b420 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55  lite3.** CONSTRU
2b430 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74  CTOR: sqlite3_st
2b440 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  mt.**.** To exec
2b450 75 74 65 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ute an SQL state
2b460 6d 65 6e 74 2c 20 69 74 20 6d 75 73 74 20 66 69  ment, it must fi
2b470 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
2b480 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
2b490 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
2b4a0 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
2b4b0 6f 75 74 69 6e 65 73 2e 20 20 4f 72 2c 20 69 6e  outines.  Or, in
2b4c0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2b4d0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2b4e0 61 72 65 20 63 6f 6e 73 74 72 75 63 74 6f 72 73  are constructors
2b4f0 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
2b500 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
2b510 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ject..**.** The 
2b520 70 72 65 66 65 72 72 65 64 20 72 6f 75 74 69 6e  preferred routin
2b530 65 20 74 6f 20 75 73 65 20 69 73 20 5b 73 71 6c  e to use is [sql
2b540 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2b550 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  )].  The.** [sql
2b560 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2b570 69 6e 74 65 72 66 61 63 65 20 69 73 20 6c 65 67  interface is leg
2b580 61 63 79 20 61 6e 64 20 73 68 6f 75 6c 64 20 62  acy and should b
2b590 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 20 5b 73  e avoided..** [s
2b5a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2b5b0 33 28 29 5d 20 68 61 73 20 61 6e 20 65 78 74 72  3()] has an extr
2b5c0 61 20 22 70 72 65 70 46 6c 61 67 73 22 20 6f 70  a "prepFlags" op
2b5d0 74 69 6f 6e 20 74 68 61 74 20 69 73 20 75 73 65  tion that is use
2b5e0 64 0a 2a 2a 20 66 6f 72 20 73 70 65 63 69 61 6c  d.** for special
2b5f0 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
2b600 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
2b610 55 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65 73  UTF-8 interfaces
2b620 20 69 73 20 70 72 65 66 65 72 72 65 64 2c 20 61   is preferred, a
2b630 73 20 53 51 4c 69 74 65 20 63 75 72 72 65 6e 74  s SQLite current
2b640 6c 79 0a 2a 2a 20 64 6f 65 73 20 61 6c 6c 20 70  ly.** does all p
2b650 61 72 73 69 6e 67 20 75 73 69 6e 67 20 55 54 46  arsing using UTF
2b660 2d 38 2e 20 20 54 68 65 20 55 54 46 2d 31 36 20  -8.  The UTF-16 
2b670 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
2b680 72 6f 76 69 64 65 64 0a 2a 2a 20 61 73 20 61 20  rovided.** as a 
2b690 63 6f 6e 76 65 6e 69 65 6e 63 65 2e 20 20 54 68  convenience.  Th
2b6a0 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72 66 61  e UTF-16 interfa
2b6b0 63 65 73 20 77 6f 72 6b 20 62 79 20 63 6f 6e 76  ces work by conv
2b6c0 65 72 74 69 6e 67 20 74 68 65 0a 2a 2a 20 69 6e  erting the.** in
2b6d0 70 75 74 20 74 65 78 74 20 69 6e 74 6f 20 55 54  put text into UT
2b6e0 46 2d 38 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 69  F-8, then invoki
2b6f0 6e 67 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ng the correspon
2b700 64 69 6e 67 20 55 54 46 2d 38 20 69 6e 74 65 72  ding UTF-8 inter
2b710 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  face..**.** The 
2b720 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
2b730 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
2b740 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2b750 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
2b760 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73  .** prior succes
2b770 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
2b780 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2b790 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2b7a0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2b7b0 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68  3_open16()].  Th
2b7c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2b7d0 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68  ction must not h
2b7e0 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e  ave been closed.
2b7f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
2b800 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
2b810 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
2b820 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
2b830 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
2b840 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
2b850 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
2b860 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2b870 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ), sqlite3_prepa
2b880 72 65 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20  re_v2(),.** and 
2b890 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2b8a0 76 33 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v3().** interfac
2b8b0 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
2b8c0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2b8d0 65 31 36 28 29 2c 20 73 71 6c 69 74 65 33 5f 70  e16(), sqlite3_p
2b8e0 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a  repare16_v2(),.*
2b8f0 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  * and sqlite3_pr
2b900 65 70 61 72 65 31 36 5f 76 33 28 29 20 75 73 65  epare16_v3() use
2b910 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
2b920 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
2b930 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76  ument is negativ
2b940 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  e, then zSql is 
2b950 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
2b960 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
2b970 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
2b980 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20  te is positive, 
2b990 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a  then it is the.*
2b9a0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
2b9b0 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
2b9c0 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  .  ^If nByte is 
2b9d0 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72  zero, then no pr
2b9e0 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
2b9f0 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64  ent is generated
2ba00 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c  ..** If the call
2ba10 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68  er knows that th
2ba20 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
2ba30 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
2ba40 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ted, then.** the
2ba50 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65  re is a small pe
2ba60 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
2ba70 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61  age to passing a
2ba80 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
2ba90 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65  r that.** is the
2baa0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2bab0 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
2bac0 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
2bad0 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
2bae0 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a  -terminator..**.
2baf0 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
2bb00 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
2bb10 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
2bb20 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
2bb30 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
2bb40 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
2bb50 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
2bb60 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
2bb70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
2bb80 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
2bb90 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
2bba0 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
2bbb0 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
2bbc0 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
2bbd0 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
2bbe0 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
2bbf0 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
2bc00 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
2bc10 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
2bc20 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
2bc30 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
2bc40 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2bc50 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
2bc60 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
2bc70 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
2bc80 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
2bc90 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
2bca0 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
2bcb0 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
2bcc0 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
2bcd0 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
2bce0 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
2bcf0 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
2bd00 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
2bd10 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
2bd20 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
2bd30 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
2bd40 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
2bd50 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
2bd60 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
2bd70 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
2bd80 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
2bd90 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
2bda0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
2bdb0 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
2bdc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
2bdd0 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
2bde0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
2bdf0 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
2be00 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
2be10 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
2be20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2be30 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2c  e3_prepare_v2(),
2be40 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2be50 5f 76 33 28 29 2c 20 73 71 6c 69 74 65 33 5f 70  _v3(), sqlite3_p
2be60 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a  repare16_v2(),.*
2be70 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  * and sqlite3_pr
2be80 65 70 61 72 65 31 36 5f 76 33 28 29 20 69 6e 74  epare16_v3() int
2be90 65 72 66 61 63 65 73 20 61 72 65 20 72 65 63 6f  erfaces are reco
2bea0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
2beb0 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 0a 2a 2a  new programs..**
2bec0 20 54 68 65 20 6f 6c 64 65 72 20 69 6e 74 65 72   The older inter
2bed0 66 61 63 65 73 20 28 73 71 6c 69 74 65 33 5f 70  faces (sqlite3_p
2bee0 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c  repare() and sql
2bef0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2bf00 29 0a 2a 2a 20 61 72 65 20 72 65 74 61 69 6e 65  ).** are retaine
2bf10 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
2bf20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62  compatibility, b
2bf30 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20  ut their use is 
2bf40 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20  discouraged..** 
2bf50 5e 49 6e 20 74 68 65 20 22 76 58 22 20 69 6e 74  ^In the "vX" int
2bf60 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
2bf70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
2bf80 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
2bf90 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
2bfa0 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
2bfb0 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
2bfc0 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
2bfd0 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
2bfe0 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
2bff0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
2c000 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
2c010 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79  have differently
2c020 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a   in three ways:.
2c030 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
2c040 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  i>.** ^If the da
2c050 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
2c060 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
2c070 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
2c080 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
2c090 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
2c0a0 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
2c0b0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
2c0c0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
2c0d0 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
2c0e0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
2c0f0 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
2c100 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b  in. As many as [
2c110 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d  SQLITE_MAX_SCHEM
2c120 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72  A_RETRY].** retr
2c130 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62  ies will occur b
2c140 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74  efore sqlite3_st
2c150 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e  ep() gives up an
2c160 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72  d returns an err
2c170 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  or..** </li>.**.
2c180 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e  ** <li>.** ^When
2c190 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
2c1a0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
2c1b0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
2c1c0 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
2c1d0 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
2c1e0 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
2c1f0 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
2c200 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61  ^The legacy beha
2c210 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
2c220 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2c230 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
2c240 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
2c250 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
2c260 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
2c270 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2c280 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
2c290 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
2c2a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2c2b0 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65  et()].** in orde
2c2c0 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
2c2d0 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
2c2e0 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
2c2f0 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
2c300 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
2c310 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
2c320 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
2c330 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
2c340 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
2c350 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
2c360 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
2c370 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62  specific value b
2c380 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74  ound to [paramet
2c390 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65  er | host parame
2c3a0 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20  ter] in the .** 
2c3b0 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67  WHERE clause mig
2c3c0 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
2c3d0 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
2c3e0 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
2c3f0 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74  ement,.** then t
2c400 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  he statement wil
2c410 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
2c420 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61  ly recompiled, a
2c430 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
2c440 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61  een .** a schema
2c450 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20   change, on the 
2c460 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f  first  [sqlite3_
2c470 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c  step()] call fol
2c480 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67  lowing any chang
2c490 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  e.** to the [sql
2c4a0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
2c4b0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
2c4c0 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20  at [parameter]. 
2c4d0 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69  .** ^The specifi
2c4e0 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45  c value of WHERE
2c4f0 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74  -clause [paramet
2c500 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  er] might influe
2c510 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69  nce the .** choi
2c520 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
2c530 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2c540 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61  r is the left-ha
2c550 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49  nd side of a [LI
2c560 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d  KE].** or [GLOB]
2c570 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20   operator or if 
2c580 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
2c590 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20   compared to an 
2c5a0 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a  indexed column.*
2c5b0 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54  * and the [SQLIT
2c5c0 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20  E_ENABLE_STAT3] 
2c5d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
2c5e0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
2c5f0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
2c600 70 3e 5e 73 71 6c 69 74 65 33 5f 70 72 65 70 61  p>^sqlite3_prepa
2c610 72 65 5f 76 33 28 29 20 64 69 66 66 65 72 73 20  re_v3() differs 
2c620 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 70 72 65  from sqlite3_pre
2c630 70 61 72 65 5f 76 32 28 29 20 6f 6e 6c 79 20 69  pare_v2() only i
2c640 6e 20 68 61 76 69 6e 67 0a 2a 2a 20 74 68 65 20  n having.** the 
2c650 65 78 74 72 61 20 70 72 65 70 46 6c 61 67 73 20  extra prepFlags 
2c660 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63 68  parameter, which
2c670 20 69 73 20 61 20 62 69 74 20 61 72 72 61 79 20   is a bit array 
2c680 63 6f 6e 73 69 73 74 69 6e 67 20 6f 66 20 7a 65  consisting of ze
2c690 72 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 6f 66  ro or.** more of
2c6a0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 50 52 45   the [SQLITE_PRE
2c6b0 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 7c  PARE_PERSISTENT|
2c6c0 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 2a  SQLITE_PREPARE_*
2c6d0 5d 20 66 6c 61 67 73 2e 20 20 5e 54 68 65 0a 2a  ] flags.  ^The.*
2c6e0 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
2c6f0 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  e_v2() interface
2c700 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 74   works exactly t
2c710 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71  he same as.** sq
2c720 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2c730 28 29 20 77 69 74 68 20 61 20 7a 65 72 6f 20 70  () with a zero p
2c740 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d 65 74  repFlags paramet
2c750 65 72 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  er..** </ol>.*/.
2c760 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
2c770 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
2c780 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2c790 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2c7a0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2c7b0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
2c7c0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2c7d0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
2c7e0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2c7f0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2c800 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2c810 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2c820 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2c830 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2c840 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2c850 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2c860 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
2c870 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2c880 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2c890 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2c8a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
2c8b0 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
2c8c0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2c8d0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2c8e0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2c8f0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
2c900 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2c910 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
2c920 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2c930 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2c940 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2c950 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2c960 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
2c970 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2c980 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2c990 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2c9a0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
2c9b0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2c9c0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2c9d0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2c9e0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
2c9f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2ca00 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2ca10 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2ca20 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2ca30 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2ca40 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2ca50 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2ca60 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
2ca70 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2ca80 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2ca90 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2caa0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2cab0 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72   unsigned int pr
2cac0 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f  epFlags, /* Zero
2cad0 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f   or more SQLITE_
2cae0 50 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a  PREPARE_ flags *
2caf0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2cb00 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2cb10 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2cb20 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2cb30 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
2cb40 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2cb50 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2cb60 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2cb70 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
2cb80 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74  epare16(.  sqlit
2cb90 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2cba0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2cbb0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2cbc0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
2cbd0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2cbe0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
2cbf0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2cc00 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2cc10 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2cc20 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2cc30 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
2cc40 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2cc50 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2cc60 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2cc70 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
2cc80 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2cc90 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2cca0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2ccb0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
2ccc0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2ccd0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2cce0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2ccf0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2cd00 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2cd10 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2cd20 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2cd30 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
2cd40 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2cd50 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2cd60 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2cd70 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2cd80 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2cd90 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2cda0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2cdb0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2cdc0 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
2cdd0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2cde0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2cdf0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2ce00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
2ce10 70 61 72 65 31 36 5f 76 33 28 0a 20 20 73 71 6c  pare16_v3(.  sql
2ce20 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2ce30 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2ce40 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2ce50 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
2ce60 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2ce70 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
2ce80 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2ce90 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2cea0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2ceb0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2cec0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69  bytes. */.  unsi
2ced0 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46 6c 61  gned int prepFla
2cee0 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d  gs, /* Zero or m
2cef0 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41  ore SQLITE_PREPA
2cf00 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73  RE_ flags */.  s
2cf10 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2cf20 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2cf30 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2cf40 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2cf50 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2cf60 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2cf70 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2cf80 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
2cf90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2cfa0 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
2cfb0 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44  nt SQL.** METHOD
2cfc0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2cfd0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2cfe0 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61  3_sql(P) interfa
2cff0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2d000 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 79 20 6f  nter to a copy o
2d010 66 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20 53  f the UTF-8.** S
2d020 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20  QL text used to 
2d030 63 72 65 61 74 65 20 5b 70 72 65 70 61 72 65 64  create [prepared
2d040 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 20 69 66   statement] P if
2d050 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 61 74 65   P was.** create
2d060 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  d by [sqlite3_pr
2d070 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
2d080 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2d090 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2d0a0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2d0b0 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  , or [sqlite3_pr
2d0c0 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a  epare16_v3()]..*
2d0d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
2d0e0 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 20 69  xpanded_sql(P) i
2d0f0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2d100 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2d110 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
2d120 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 53  containing the S
2d130 51 4c 20 74 65 78 74 20 6f 66 20 70 72 65 70 61  QL text of prepa
2d140 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20  red statement P 
2d150 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70  with.** [bound p
2d160 61 72 61 6d 65 74 65 72 73 5d 20 65 78 70 61 6e  arameters] expan
2d170 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
2d180 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 20 70   example, if a p
2d190 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d1a0 74 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69  t is created usi
2d1b0 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65  ng the SQL.** te
2d1c0 78 74 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c  xt "SELECT $abc,
2d1d0 3a 78 79 7a 22 20 61 6e 64 20 69 66 20 70 61 72  :xyz" and if par
2d1e0 61 6d 65 74 65 72 20 24 61 62 63 20 69 73 20 62  ameter $abc is b
2d1f0 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67 65 72 20  ound to integer 
2d200 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61  2345.** and para
2d210 6d 65 74 65 72 20 3a 78 79 7a 20 69 73 20 75 6e  meter :xyz is un
2d220 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69  bound, then sqli
2d230 74 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72  te3_sql() will r
2d240 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69  eturn.** the ori
2d250 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20 22 53  ginal string, "S
2d260 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22  ELECT $abc,:xyz"
2d270 20 62 75 74 20 73 71 6c 69 74 65 33 5f 65 78 70   but sqlite3_exp
2d280 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77  anded_sql().** w
2d290 69 6c 6c 20 72 65 74 75 72 6e 20 22 53 45 4c 45  ill return "SELE
2d2a0 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e  CT 2345,NULL".)^
2d2b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2d2c0 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2d2d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2d2e0 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73  urns NULL if ins
2d2f0 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
2d300 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61 62 6c 65  .** is available
2d310 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
2d320 75 6c 74 2c 20 6f 72 20 69 66 20 74 68 65 20 72  ult, or if the r
2d330 65 73 75 6c 74 20 77 6f 75 6c 64 20 65 78 63 65  esult would exce
2d340 65 64 20 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61  ed the.** the ma
2d350 78 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e  ximum string len
2d360 67 74 68 20 64 65 74 65 72 6d 69 6e 65 64 20 62  gth determined b
2d370 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49  y the [SQLITE_LI
2d380 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a  MIT_LENGTH]..**.
2d390 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
2d3a0 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
2d3b0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
2d3c0 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65  ption limits the
2d3d0 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e   size of.** boun
2d3e0 64 20 70 61 72 61 6d 65 74 65 72 20 65 78 70 61  d parameter expa
2d3f0 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53  nsions.  ^The [S
2d400 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45  QLITE_OMIT_TRACE
2d410 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
2d420 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73 65 73 20  * option causes 
2d430 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2d440 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77 61 79 73  _sql() to always
2d450 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a   return NULL..**
2d460 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20  .** ^The string 
2d470 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2d480 74 65 33 5f 73 71 6c 28 50 29 20 69 73 20 6d 61  te3_sql(P) is ma
2d490 6e 61 67 65 64 20 62 79 20 53 51 4c 69 74 65 20  naged by SQLite 
2d4a0 61 6e 64 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  and is.** automa
2d4b0 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20 77 68  tically freed wh
2d4c0 65 6e 20 74 68 65 20 70 72 65 70 61 72 65 64 20  en the prepared 
2d4d0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e  statement is fin
2d4e0 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  alized..** ^The 
2d4f0 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20  string returned 
2d500 62 79 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  by sqlite3_expan
2d510 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e 20 74  ded_sql(P), on t
2d520 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c 0a 2a  he other hand,.*
2d530 2a 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72  * is obtained fr
2d540 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2d550 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73 74 20 62  oc()] and must b
2d560 65 20 66 72 65 65 20 62 79 20 74 68 65 20 61 70  e free by the ap
2d570 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62 79 20  plication.** by 
2d580 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
2d590 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
2d5a0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2d5b0 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
2d5c0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2d5d0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65  .char *sqlite3_e
2d5e0 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69  xpanded_sql(sqli
2d5f0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2d600 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d610 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
2d620 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2d630 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61   Writes The Data
2d640 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  base.** METHOD: 
2d650 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2d660 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2d670 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29  stmt_readonly(X)
2d680 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2d690 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
2d6a0 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  o) if.** and onl
2d6b0 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72  y if the [prepar
2d6c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
2d6d0 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20  makes no direct 
2d6e0 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68  changes to.** th
2d6f0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2d700 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
2d710 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2d720 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2d730 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2d740 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75  ns] or.** [virtu
2d750 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74  al tables] might
2d760 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2d770 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20  base indirectly 
2d780 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74  as a side effect
2d790 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .  .** ^(For exa
2d7a0 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c  mple, if an appl
2d7b0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20  ication defines 
2d7c0 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c  a function "eval
2d7d0 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c  ()" that .** cal
2d7e0 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ls [sqlite3_exec
2d7f0 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  ()], then the fo
2d800 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74  llowing SQL stat
2d810 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63  ement would.** c
2d820 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
2d830 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20  se file through 
2d840 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a  side-effects:.**
2d850 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2d860 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45  <pre>.**    SELE
2d870 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20  CT eval('DELETE 
2d880 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74  FROM t1') FROM t
2d890 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  2;.** </pre></bl
2d8a0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
2d8b0 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20  But because the 
2d8c0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2d8d0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nt does not chan
2d8e0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
2d8f0 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79  file.** directly
2d900 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  , sqlite3_stmt_r
2d910 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20  eadonly() would 
2d920 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75  still return tru
2d930 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e  e.)^.**.** ^Tran
2d940 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20  saction control 
2d950 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20  statements such 
2d960 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d  as [BEGIN], [COM
2d970 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d  MIT], [ROLLBACK]
2d980 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d  ,.** [SAVEPOINT]
2d990 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20  , and [RELEASE] 
2d9a0 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74  cause sqlite3_st
2d9b0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
2d9c0 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a   return true,.**
2d9d0 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65   since the state
2d9e0 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
2d9f0 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   do not actually
2da00 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
2da10 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68  base but.** rath
2da20 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20  er they control 
2da30 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68  the timing of wh
2da40 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65  en other stateme
2da50 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a  nts modify the .
2da60 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54  ** database.  ^T
2da70 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20  he [ATTACH] and 
2da80 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65  [DETACH] stateme
2da90 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a  nts also cause.*
2daa0 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
2dab0 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
2dac0 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20  urn true since, 
2dad0 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74  while those stat
2dae0 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65  ements.** change
2daf0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
2db00 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  on of a database
2db10 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65   connection, the
2db20 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a  y do not make .*
2db30 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  * changes to the
2db40 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2db50 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
2db60 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65 20  n disk..** ^The 
2db70 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2db80 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66 61 63  donly() interfac
2db90 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 66  e returns true f
2dba0 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e 63 65  or [BEGIN] since
2dbb0 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65 72 65  .** [BEGIN] mere
2dbc0 6c 79 20 73 65 74 73 20 69 6e 74 65 72 6e 61 6c  ly sets internal
2dbd0 20 66 6c 61 67 73 2c 20 62 75 74 20 74 68 65 20   flags, but the 
2dbe0 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 49 4d 4d  [BEGIN|BEGIN IMM
2dbf0 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b  EDIATE] and.** [
2dc00 42 45 47 49 4e 7c 42 45 47 49 4e 20 45 58 43 4c  BEGIN|BEGIN EXCL
2dc10 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64 73 20  USIVE] commands 
2dc20 64 6f 20 74 6f 75 63 68 20 74 68 65 20 64 61 74  do touch the dat
2dc30 61 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a 2a 20  abase and so.** 
2dc40 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2dc50 64 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e 73 20  donly() returns 
2dc60 66 61 6c 73 65 20 66 6f 72 20 74 68 6f 73 65 20  false for those 
2dc70 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 69 6e 74  commands..*/.int
2dc80 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2dc90 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73  adonly(sqlite3_s
2dca0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2dcb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2dcc0 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65  termine If A Pre
2dcd0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2dce0 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a  Has Been Reset.*
2dcf0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2dd00 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2dd10 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
2dd20 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65  usy(S) interface
2dd30 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
2dd40 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a  on-zero) if the.
2dd50 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2dd60 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65  tement] S has be
2dd70 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65  en stepped at le
2dd80 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a  ast once using .
2dd90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2dda0 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65 69  (S)] but has nei
2ddb0 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70  ther run to comp
2ddc0 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 64  letion (returned
2ddd0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
2dde0 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  ] from [sqlite3_
2ddf0 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a  step(S)]) nor.**
2de00 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e   been reset usin
2de10 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2de20 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  (S)].  ^The sqli
2de30 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
2de40 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
2de50 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53  turns false if S
2de60 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2de70 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74  er.  If S is not
2de80 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e   a .** NULL poin
2de90 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ter and is not a
2dea0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
2deb0 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  lid [prepared st
2dec0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
2ded0 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ct, then the beh
2dee0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2def0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
2df00 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a  undesirable..**.
2df10 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
2df20 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  e can be used in
2df30 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71   combination [sq
2df40 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
2df50 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20  )].** to locate 
2df60 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61  all prepared sta
2df70 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
2df80 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ed with a databa
2df90 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  se .** connectio
2dfa0 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65  n that are in ne
2dfb0 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65  ed of being rese
2dfc0 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20  t.  This can be 
2dfd0 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61  used,.** for exa
2dfe0 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73  mple, in diagnos
2dff0 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tic routines to 
2e000 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61  search for prepa
2e010 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  red .** statemen
2e020 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64  ts that are hold
2e030 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
2e040 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  n open..*/.int s
2e050 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
2e060 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2e070 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e080 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
2e090 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
2e0a0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
2e0b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2e0c0 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
2e0d0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2e0e0 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
2e0f0 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
2e100 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
2e110 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
2e120 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
2e130 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
2e140 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
2e150 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
2e160 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
2e170 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
2e180 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
2e190 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
2e1a0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2e1b0 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
2e1c0 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
2e1d0 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
2e1e0 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
2e1f0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
2e200 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2e210 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
2e220 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
2e230 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
2e240 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
2e250 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
2e260 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e270 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
2e280 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
2e290 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
2e2a0 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
2e2b0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
2e2c0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
2e2d0 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
2e2e0 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
2e2f0 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
2e300 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
2e310 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
2e320 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
2e330 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e340 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  value.  The.** [
2e350 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
2e360 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  p()] interface c
2e370 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f  an be used to co
2e380 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a  nstruct a new .*
2e390 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  * protected sqli
2e3a0 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61  te3_value from a
2e3b0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
2e3c0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
2e3d0 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
2e3e0 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
2e3f0 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
2e400 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
2e410 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
2e420 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72   held.  An inter
2e430 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
2e440 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
2e450 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2e460 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
2e470 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
2e480 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
2e490 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2e4a0 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
2e4b0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
2e4c0 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
2e4d0 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
2e4e0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
2e4f0 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
2e500 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
2e510 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
2e520 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
2e530 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
2e540 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
2e550 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
2e560 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
2e570 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
2e580 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
2e590 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
2e5a0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
2e5b0 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
2e5c0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
2e5d0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
2e5e0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2e5f0 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
2e600 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
2e610 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
2e620 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
2e630 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
2e640 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
2e650 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
2e660 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
2e670 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
2e680 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
2e690 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
2e6a0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
2e6b0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2e6c0 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
2e6d0 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
2e6e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2e6f0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2e700 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
2e710 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
2e720 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
2e730 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
2e740 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2e750 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2e760 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
2e770 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2e780 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
2e790 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
2e7a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2e7b0 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
2e7c0 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
2e7d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e7e0 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
2e7f0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 61 73 20  only be used as 
2e800 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20  arguments.** to 
2e810 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2e820 76 61 6c 75 65 28 29 5d 2c 20 5b 73 71 6c 69 74  value()], [sqlit
2e830 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
2e840 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2e850 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e 0a  3_value_dup()]..
2e860 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
2e870 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c  value_blob | sql
2e880 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
2e890 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  )] family of.** 
2e8a0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
2e8b0 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  re protected sql
2e8c0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2e8d0 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ts..*/.typedef s
2e8e0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 61  truct sqlite3_va
2e8f0 6c 75 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  lue sqlite3_valu
2e900 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
2e910 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
2e920 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a   Context Object.
2e930 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
2e940 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
2e950 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
2e960 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
2e970 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
2e980 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
2e990 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ^A pointer to an
2e9a0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2e9b0 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c   object.** is al
2e9c0 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
2e9d0 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61  eter to [applica
2e9e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2e9f0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
2ea00 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  The application-
2ea10 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2ea20 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
2ea30 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68  ion will pass th
2ea40 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68  is.** pointer th
2ea50 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73  rough into calls
2ea60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2ea70 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  ult_int | sqlite
2ea80 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20  3_result()],.** 
2ea90 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
2eaa0 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b  te_context()], [
2eab0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2eac0 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  a()],.** [sqlite
2ead0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
2eae0 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  dle()], [sqlite3
2eaf0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c  _get_auxdata()],
2eb00 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69  .** and/or [sqli
2eb10 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2eb20 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
2eb30 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
2eb40 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
2eb50 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
2eb60 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20  PI3REF: Binding 
2eb70 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
2eb80 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed Statements.**
2eb90 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74   KEYWORDS: {host
2eba0 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73   parameter} {hos
2ebb0 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68  t parameters} {h
2ebc0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
2ebd0 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  me}.** KEYWORDS:
2ebe0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d   {SQL parameter}
2ebf0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   {SQL parameters
2ec00 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  } {parameter bin
2ec10 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ding}.** METHOD:
2ec20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2ec30 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c  .** ^(In the SQL
2ec40 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
2ec50 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
2ec60 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2ec70 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
2ec80 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
2ec90 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
2eca0 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74   a [parameter] t
2ecb0 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20  hat matches one 
2ecc0 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  of following.** 
2ecd0 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a  templates:.**.**
2ece0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
2ecf0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
2ed00 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
2ed10 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
2ed20 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
2ed30 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74  >.**.** In the t
2ed40 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20  emplates above, 
2ed50 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61  NNN represents a
2ed60 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
2ed70 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65  l,.** and VVV re
2ed80 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68  presents an alph
2ed90 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66  anumeric identif
2eda0 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c  ier.)^  ^The val
2edb0 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
2edc0 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
2edd0 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
2ede0 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
2edf0 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
2ee00 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
2ee10 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
2ee20 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2ee30 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
2ee40 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  re..**.** ^The f
2ee50 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
2ee60 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2ee70 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69  d_*() routines i
2ee80 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f  s always.** a po
2ee90 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
2eea0 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
2eeb0 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
2eec0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2eed0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
2eee0 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a  s variants..**.*
2eef0 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
2ef00 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
2ef10 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70  dex of the SQL p
2ef20 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
2ef30 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  et..** ^The left
2ef40 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
2ef50 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
2ef60 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65  of 1.  ^When the
2ef70 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53   same named.** S
2ef80 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
2ef90 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
2efa0 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
2efb0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
2efc0 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
2efd0 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
2efe0 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
2eff0 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69  rence..** ^The i
2f000 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
2f010 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
2f020 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
2f030 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
2f040 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2f050 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20  index()] API if 
2f060 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69  desired.  ^The i
2f070 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
2f080 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
2f090 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
2f0a0 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76  N..** ^The NNN v
2f0b0 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
2f0c0 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
2f0d0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
2f0e0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
2f0f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
2f100 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
2f110 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
2f120 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  )..**.** ^The th
2f130 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
2f140 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
2f150 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
2f160 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
2f170 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
2f180 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2f190 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
2f1a0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
2f1b0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
2f1c0 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55  d_blob() is a NU
2f1d0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
2f1e0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2f1f0 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72  eter.** is ignor
2f200 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72  ed and the end r
2f210 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d  esult is the sam
2f220 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e  e as sqlite3_bin
2f230 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20  d_null()..**.** 
2f240 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  ^(In those routi
2f250 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
2f260 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
2f270 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
2f280 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
2f290 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
2f2a0 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
2f2b0 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
2f2c0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2f2d0 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
2f2e0 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
2f2f0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
2f300 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a  characters.)^.**
2f310 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
2f320 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2f330 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
2f340 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2f350 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20  _text16().** is 
2f360 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
2f370 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
2f380 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68   string is.** th
2f390 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2f3a0 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
2f3b0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
2f3c0 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75  r..** If the fou
2f3d0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
2f3e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2f3f0 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  ob() is negative
2f400 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65  , then.** the be
2f410 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
2f420 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e  ned..** If a non
2f430 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68  -negative fourth
2f440 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
2f450 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65  ovided to sqlite
2f460 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a  3_bind_text().**
2f470 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2f480 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c  _text16() or sql
2f490 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2f4a0 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20  () then.** that 
2f4b0 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
2f4c0 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
2f4d0 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e  t.** where the N
2f4e0 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
2f4f0 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69  uld occur assumi
2f500 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65  ng the string we
2f510 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e  re NUL.** termin
2f520 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
2f530 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
2f540 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65  ur at byte offse
2f550 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a  ts less than .**
2f560 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2f570 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2f580 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  er then the resu
2f590 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c  lting string val
2f5a0 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61  ue will.** conta
2f5b0 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
2f5c0 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66  .  The result of
2f5d0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76   expressions inv
2f5e0 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a  olving strings.*
2f5f0 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  * with embedded 
2f600 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
2f610 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  d..**.** ^The fi
2f620 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
2f630 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72  the BLOB and str
2f640 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65  ing binding inte
2f650 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64  rfaces.** is a d
2f660 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
2f670 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
2f680 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
2f690 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
2f6a0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
2f6b0 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74  h it.  ^The dest
2f6c0 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
2f6d0 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  .** to dispose o
2f6e0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  f the BLOB or st
2f6f0 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ring even if the
2f700 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50   call to bind AP
2f710 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20  I fails..** ^If 
2f720 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
2f730 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
2f740 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
2f750 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
2f760 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
2f770 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
2f780 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
2f790 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
2f7a0 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
2f7b0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
2f7c0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
2f7d0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
2f7e0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
2f7f0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
2f800 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
2f810 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
2f820 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
2f830 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
2f840 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
2f850 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2f860 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
2f870 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
2f880 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ixth argument to
2f890 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2f8a0 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f  xt64() must be o
2f8b0 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45  ne of.** [SQLITE
2f8c0 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
2f8d0 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f  UTF16], [SQLITE_
2f8e0 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51  UTF16BE], or [SQ
2f8f0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a  LITE_UTF16LE].**
2f900 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
2f910 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20  encoding of the 
2f920 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69 72  text in the thir
2f930 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66  d parameter.  If
2f940 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61 72  .** the sixth ar
2f950 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
2f960 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
2f970 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
2f980 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c  e.** allowed val
2f990 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c  ues shown above,
2f9a0 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74 20   or if the text 
2f9b0 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
2f9c0 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68  erent.** from th
2f9d0 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
2f9e0 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78 74  fied by the sixt
2f9f0 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  h parameter, the
2fa00 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  n the behavior.*
2fa10 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
2fa20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2fa30 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
2fa40 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
2fa50 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
2fa60 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
2fa70 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
2fa80 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
2fa90 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
2faa0 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
2fab0 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
2fac0 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
2fad0 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
2fae0 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
2faf0 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
2fb00 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
2fb10 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
2fb20 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
2fb30 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
2fb40 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
2fb50 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2fb60 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
2fb70 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
2fb80 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
2fb90 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
2fba0 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
2fbb0 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
2fbc0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
2fbd0 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  B..**.** ^The sq
2fbe0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74  lite3_bind_point
2fbf0 65 72 28 53 2c 49 2c 50 2c 54 2c 44 29 20 72 6f  er(S,I,P,T,D) ro
2fc00 75 74 69 6e 65 20 63 61 75 73 65 73 20 74 68 65  utine causes the
2fc10 20 49 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   I-th parameter 
2fc20 69 6e 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  in.** [prepared 
2fc30 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 74 6f 20  statement] S to 
2fc40 68 61 76 65 20 61 6e 20 53 51 4c 20 76 61 6c 75  have an SQL valu
2fc50 65 20 6f 66 20 4e 55 4c 4c 2c 20 62 75 74 20 74  e of NULL, but t
2fc60 6f 20 61 6c 73 6f 20 62 65 0a 2a 2a 20 61 73 73  o also be.** ass
2fc70 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
2fc80 20 70 6f 69 6e 74 65 72 20 50 20 6f 66 20 74 79   pointer P of ty
2fc90 70 65 20 54 2e 20 20 5e 44 20 69 73 20 65 69 74  pe T.  ^D is eit
2fca0 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
2fcb0 65 72 20 6f 72 0a 2a 2a 20 61 20 70 6f 69 6e 74  er or.** a point
2fcc0 65 72 20 74 6f 20 61 20 64 65 73 74 72 75 63 74  er to a destruct
2fcd0 6f 72 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20  or function for 
2fce0 50 2e 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  P. ^SQLite will 
2fcf0 69 6e 76 6f 6b 65 20 74 68 65 0a 2a 2a 20 64 65  invoke the.** de
2fd00 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 68 20  structor D with 
2fd10 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
2fd20 74 20 6f 66 20 50 20 77 68 65 6e 20 69 74 20 69  t of P when it i
2fd30 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
2fd40 0a 2a 2a 20 50 2e 20 20 54 68 65 20 54 20 70 61  .** P.  The T pa
2fd50 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62  rameter should b
2fd60 65 20 61 20 73 74 61 74 69 63 20 73 74 72 69 6e  e a static strin
2fd70 67 2c 20 70 72 65 66 65 72 61 62 6c 79 20 61 20  g, preferably a 
2fd80 73 74 72 69 6e 67 0a 2a 2a 20 6c 69 74 65 72 61  string.** litera
2fd90 6c 2e 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  l. The sqlite3_b
2fda0 69 6e 64 5f 70 6f 69 6e 74 65 72 28 29 20 72 6f  ind_pointer() ro
2fdb0 75 74 69 6e 65 20 69 73 20 70 61 72 74 20 6f 66  utine is part of
2fdc0 20 74 68 65 0a 2a 2a 20 5b 70 6f 69 6e 74 65 72   the.** [pointer
2fdd0 20 70 61 73 73 69 6e 67 20 69 6e 74 65 72 66 61   passing interfa
2fde0 63 65 5d 20 61 64 64 65 64 20 66 6f 72 20 53 51  ce] added for SQ
2fdf0 4c 69 74 65 20 33 2e 32 30 2e 30 2e 0a 2a 2a 0a  Lite 3.20.0..**.
2fe00 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68  ** ^If any of th
2fe10 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2fe20 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
2fe30 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
2fe40 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f  LL pointer.** fo
2fe50 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2fe60 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69  statement] or wi
2fe70 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74  th a prepared st
2fe80 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63  atement for whic
2fe90 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  h.** [sqlite3_st
2fea0 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  ep()] has been c
2feb0 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e  alled more recen
2fec0 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65  tly than [sqlite
2fed0 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74  3_reset()],.** t
2fee0 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c  hen the call wil
2fef0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
2ff00 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e  _MISUSE].  If an
2ff10 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28  y sqlite3_bind_(
2ff20 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20  ).** routine is 
2ff30 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72  passed a [prepar
2ff40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2ff50 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  at has been fina
2ff60 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65  lized, the.** re
2ff70 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
2ff80 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68  d and probably h
2ff90 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42  armful..**.** ^B
2ffa0 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
2ffb0 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
2ffc0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2ffd0 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e   routine..** ^Un
2ffe0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
2fff0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
30000 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
30010 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
30020 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74  d_* routines ret
30030 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
30040 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
30050 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
30060 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65   if anything goe
30070 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51  s wrong..** ^[SQ
30080 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67  LITE_TOOBIG] mig
30090 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69  ht be returned i
300a0 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20  f the size of a 
300b0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a  string or BLOB.*
300c0 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73  * exceeds limits
300d0 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c   imposed by [sql
300e0 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
300f0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
30100 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  ]) or.** [SQLITE
30110 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a  _MAX_LENGTH]..**
30120 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d   ^[SQLITE_RANGE]
30130 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
30140 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
30150 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
30160 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54   range.  ^[SQLIT
30170 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
30180 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
30190 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65   fails..**.** Se
301a0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
301b0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
301c0 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
301d0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
301e0 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
301f0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
30200 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
30210 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
30220 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c  e3_bind_blob(sql
30230 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
30240 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
30250 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
30260 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
30270 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71  3_bind_blob64(sq
30280 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30290 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73  , const void*, s
302a0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20  qlite3_uint64,. 
302b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
302c0 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76         void(*)(v
302d0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
302e0 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28  te3_bind_double(
302f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30300 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74  nt, double);.int
30310 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
30320 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
30330 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20   int, int);.int 
30340 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
30350 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
30360 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69  , int, sqlite3_i
30370 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74  nt64);.int sqlit
30380 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
30390 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
303a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
303b0 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  nd_text(sqlite3_
303c0 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  stmt*,int,const 
303d0 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a  char*,int,void(*
303e0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
303f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
30400 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
30410 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
30420 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
30430 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
30440 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
30450 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
30460 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
30470 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
30480 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
30490 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
304a0 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69  (*)(void*), unsi
304b0 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69  gned char encodi
304c0 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ng);.int sqlite3
304d0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
304e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
304f0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
30500 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
30510 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28  e3_bind_pointer(
30520 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30530 6e 74 2c 20 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  nt, void*, const
30540 20 63 68 61 72 2a 2c 76 6f 69 64 28 2a 29 28 76   char*,void(*)(v
30550 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
30560 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
30570 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
30580 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e   int, int n);.in
30590 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
305a0 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  eroblob64(sqlite
305b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
305c0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a  lite3_uint64);..
305d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
305e0 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
305f0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48  rameters.** METH
30600 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
30610 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
30620 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
30630 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
30640 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
30650 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
30660 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30670 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
30680 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
30690 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
306a0 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
306b0 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
306c0 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
306d0 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
306e0 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
306f0 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
30700 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
30710 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
30720 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
30730 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
30740 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
30750 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
30760 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
30770 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
30780 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
30790 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
307a0 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
307b0 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
307c0 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
307d0 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
307e0 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
307f0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
30800 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
30810 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
30820 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
30830 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
30840 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
30850 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
30860 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
30870 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
30880 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
30890 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
308a0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
308b0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
308c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
308d0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
308e0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
308f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
30900 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
30910 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f  rameter.** METHO
30920 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
30930 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30940 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
30950 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65  r_name(P,N) inte
30960 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
30970 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
30980 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d   N-th [SQL param
30990 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72  eter] in the [pr
309a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
309b0 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61  ] P..** ^(SQL pa
309c0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
309d0 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  form "?NNN" or "
309e0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
309f0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76  or "$AAA".** hav
30a00 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69  e a name which i
30a10 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e  s the string "?N
30a20 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
30a30 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
30a40 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ".** respectivel
30a50 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  y..** In other w
30a60 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61  ords, the initia
30a70 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20  l ":" or "$" or 
30a80 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73  "@" or "?".** is
30a90 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
30aa0 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e  t of the name.)^
30ab0 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20  .** ^Parameters 
30ac0 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20  of the form "?" 
30ad0 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77  without a follow
30ae0 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65  ing integer have
30af0 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20   no name.** and 
30b00 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20  are referred to 
30b10 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72  as "nameless" or
30b20 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61   "anonymous para
30b30 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e  meters"..**.** ^
30b40 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
30b50 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
30b60 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
30b70 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  0..**.** ^If the
30b80 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20   value N is out 
30b90 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74  of range or if t
30ba0 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65  he N-th paramete
30bb0 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73  r is.** nameless
30bc0 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72  , then NULL is r
30bd0 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72  eturned.  ^The r
30be0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
30bf0 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
30c00 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
30c10 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
30c20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
30c30 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
30c40 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
30c50 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
30c60 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 5b 73 71  are16()],.** [sq
30c70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
30c80 76 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  v2()], or [sqlit
30c90 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
30ca0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
30cb0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
30cc0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
30cd0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
30ce0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
30cf0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
30d00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
30d10 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
30d20 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  x()]..*/.const c
30d30 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
30d40 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
30d50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30d60 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
30d70 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
30d80 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
30d90 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a   A Given Name.**
30da0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
30db0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  _stmt.**.** ^Ret
30dc0 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
30dd0 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
30de0 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
30df0 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78  .  ^The.** index
30e00 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
30e10 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
30e20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
30e30 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
30e40 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
30e50 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
30e60 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a  d()].  ^A zero.*
30e70 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
30e80 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
30e90 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
30ea0 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
30eb0 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
30ec0 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
30ed0 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
30ee0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
30ef0 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
30f00 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
30f10 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
30f20 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
30f30 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
30f40 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a  epare16_v3()]..*
30f50 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
30f60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
30f70 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
30f80 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
30f90 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
30fa0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
30fb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
30fc0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a  ameter_name()]..
30fd0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
30fe0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
30ff0 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
31000 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
31010 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
31020 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
31030 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
31040 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
31050 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  nt.** METHOD: sq
31060 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
31070 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68   ^Contrary to th
31080 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
31090 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
310a0 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
310b0 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
310c0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
310d0 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
310e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
310f0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74  ment]..** ^Use t
31100 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72  his routine to r
31110 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
31120 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
31130 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
31140 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
31150 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
31160 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31170 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
31180 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
31190 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
311a0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
311b0 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d   ^Return the num
311c0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
311d0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
311e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
311f0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
31200 61 74 65 6d 65 6e 74 5d 2e 20 5e 49 66 20 74 68  atement]. ^If th
31210 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
31220 6e 73 20 30 2c 20 74 68 61 74 20 6d 65 61 6e 73  ns 0, that means
31230 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72   the .** [prepar
31240 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 72 65  ed statement] re
31250 74 75 72 6e 73 20 6e 6f 20 64 61 74 61 20 28 66  turns no data (f
31260 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55  or example an [U
31270 50 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e 48 6f 77  PDATE])..** ^How
31280 65 76 65 72 2c 20 6a 75 73 74 20 62 65 63 61 75  ever, just becau
31290 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
312a0 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69  returns a positi
312b0 76 65 20 6e 75 6d 62 65 72 20 64 6f 65 73 20 6e  ve number does n
312c0 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  ot.** mean that 
312d0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 72 6f 77 73  one or more rows
312e0 20 6f 66 20 64 61 74 61 20 77 69 6c 6c 20 62 65   of data will be
312f0 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 41 20 53   returned.  ^A S
31300 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 0a  ELECT statement.
31310 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 68  ** will always h
31320 61 76 65 20 61 20 70 6f 73 69 74 69 76 65 20 73  ave a positive s
31330 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
31340 75 6e 74 28 29 20 62 75 74 20 64 65 70 65 6e 64  unt() but depend
31350 69 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a 20 57 48  ing on the.** WH
31360 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74  ERE clause const
31370 72 61 69 6e 74 73 20 61 6e 64 20 74 68 65 20 74  raints and the t
31380 61 62 6c 65 20 63 6f 6e 74 65 6e 74 2c 20 69 74  able content, it
31390 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 6e 6f   might return no
313a0 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   rows..**.** See
313b0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
313c0 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  data_count()].*/
313d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
313e0 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
313f0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
31400 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31410 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
31420 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
31430 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
31440 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
31450 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
31460 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
31470 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
31480 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
31490 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
314a0 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
314b0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20  tatement.  ^The 
314c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
314d0 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
314e0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
314f0 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
31500 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
31510 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
31520 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
31530 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
31540 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
31550 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
31560 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
31570 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
31580 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65  eter is the [pre
31590 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
315a0 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  .** that impleme
315b0 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  nts the [SELECT]
315c0 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65   statement. ^The
315d0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
315e0 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r is the.** colu
315f0 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65  mn number.  ^The
31600 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
31610 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a   is number 0..**
31620 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
31630 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  d string pointer
31640 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
31650 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70  either the [prep
31660 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
31670 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ** is destroyed 
31680 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  by [sqlite3_fina
31690 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
316a0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
316b0 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
316c0 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
316d0 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
316e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
316f0 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
31700 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
31710 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
31720 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
31730 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f  _column_name() o
31740 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
31750 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65  _name16() on the
31760 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   same column..**
31770 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
31780 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64  malloc() fails d
31790 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73  uring the proces
317a0 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72  sing of either r
317b0 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65  outine.** (for e
317c0 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20  xample during a 
317d0 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
317e0 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29  UTF-8 to UTF-16)
317f0 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20   then a.** NULL 
31800 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
31810 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
31820 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
31830 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
31840 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
31850 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
31860 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
31870 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
31880 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
31890 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
318a0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
318b0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
318c0 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
318d0 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
318e0 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
318f0 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
31900 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74  e next..*/.const
31910 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
31920 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
31930 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
31940 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
31950 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
31960 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
31970 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
31980 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
31990 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
319a0 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20  Query Result.** 
319b0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
319c0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  stmt.**.** ^Thes
319d0 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
319e0 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
319f0 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61  termine the data
31a00 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
31a10 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  .** table column
31a20 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69   that is the ori
31a30 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75  gin of a particu
31a40 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  lar result colum
31a50 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d  n in.** [SELECT]
31a60 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
31a70 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
31a80 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
31a90 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
31aa0 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
31ab0 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
31ac0 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
31ad0 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61  g.  ^The _databa
31ae0 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
31af0 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
31b00 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
31b10 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
31b20 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
31b30 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
31b40 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
31b50 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
31b60 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68  umn name..** ^Th
31b70 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
31b80 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
31b90 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
31ba0 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
31bb0 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
31bc0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31bd0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
31be0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
31bf0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
31c00 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
31c10 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
31c20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
31c30 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
31c40 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
31c50 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
31c60 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
31c70 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
31c80 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
31c90 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ding..**.** ^The
31ca0 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
31cb0 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
31cc0 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
31cd0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
31ce0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
31cf0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
31d00 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
31d10 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  nt to these inte
31d20 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65  rfaces is a [pre
31d30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31d40 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  ..** ^These func
31d50 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
31d60 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
31d70 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
31d80 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
31d90 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
31da0 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
31db0 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
31dc0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  n argument..** ^
31dd0 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
31de0 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30  lumn is column 0
31df0 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
31e00 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  nes..**.** ^If t
31e10 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
31e20 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
31e30 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
31e40 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73  pression or.** s
31e50 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
31e60 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
31e70 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
31e80 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
31e90 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20  eturn.** NULL.  
31ea0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d  ^These routine m
31eb0 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e  ight also return
31ec0 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72   NULL if a memor
31ed0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
31ee0 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e  or.** occurs.  ^
31ef0 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
31f00 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
31f10 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
31f20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
31f30 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68  .** or column th
31f40 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
31f50 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
31f60 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
31f70 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74   ^As with all ot
31f80 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
31f90 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d   those whose nam
31fa0 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22  es end with "16"
31fb0 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
31fc0 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
31fd0 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  s and the other 
31fe0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
31ff0 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54   UTF-8..**.** ^T
32000 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
32010 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
32020 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
32030 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
32040 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
32050 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
32060 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
32070 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a  sor symbol..**.*
32080 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
32090 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
320a0 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
320b0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
320c0 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
320d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
320e0 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
320f0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
32100 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
32110 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
32120 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
32130 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
32140 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
32150 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
32160 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
32170 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
32180 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
32190 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b  * for the same [
321a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
321b0 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
321c0 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20  olumn.** at the 
321d0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
321e0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
321f0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e  ndefined..*/.con
32200 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
32210 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
32220 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
32230 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
32240 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
32250 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
32260 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
32270 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
32280 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
32290 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
322a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
322b0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
322c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
322d0 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
322e0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
322f0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
32300 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
32310 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
32320 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
32330 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
32340 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
32350 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
32360 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
32370 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
32380 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
32390 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d  uery Result.** M
323a0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
323b0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  tmt.**.** ^(The 
323c0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
323d0 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
323e0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
323f0 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
32400 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  is a [SELECT] st
32410 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
32420 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
32430 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65  e.** returned re
32440 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74  sult set of that
32450 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74   [SELECT] is a t
32460 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
32470 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
32480 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
32490 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
324a0 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
324b0 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
324c0 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66  returned.)^  ^If
324d0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
324e0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
324f0 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
32500 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
32510 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
32520 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
32530 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  ed..** ^The retu
32540 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61  rned string is a
32550 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f  lways UTF-8 enco
32560 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
32570 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20   example, given 
32580 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
32590 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
325a0 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
325b0 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e  RIANT);.**.** an
325c0 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
325d0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
325e0 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
325f0 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
32600 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
32610 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
32620 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
32630 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
32640 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72  for the second r
32650 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
32660 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
32670 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
32680 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
32690 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e  column (i==0).)^
326a0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
326b0 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
326c0 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53  time typing.  ^S
326d0 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61  o just because a
326e0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65   column.** is de
326f0 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69  clared to contai
32700 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74  n a particular t
32710 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61  ype does not mea
32720 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61  n that the.** da
32730 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61  ta stored in tha
32740 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74  t column is of t
32750 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
32760 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  .  SQLite is.** 
32770 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20  strongly typed, 
32780 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69  but the typing i
32790 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74  s dynamic not st
327a0 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20  atic.  ^Type.** 
327b0 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
327c0 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
327d0 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
327e0 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
327f0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
32800 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63  ose values..*/.c
32810 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
32820 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
32830 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
32840 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
32850 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
32860 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
32870 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
32880 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32890 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51  : Evaluate An SQ
328a0 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d  L Statement.** M
328b0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
328c0 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  tmt.**.** After 
328d0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
328e0 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
328f0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 61  prepared using a
32900 6e 79 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ny of.** [sqlite
32910 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
32920 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32930 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v3()], [sqlite
32940 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
32950 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
32960 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
32970 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  ] or one of the 
32980 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
32990 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
329a0 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c  epare()] or [sql
329b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
329c0 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ], this function
329d0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  .** must be call
329e0 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
329f0 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65  imes to evaluate
32a00 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a   the statement..
32a10 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
32a20 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
32a30 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
32a40 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63  _step() interfac
32a50 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77  e depend.** on w
32a60 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65  hether the state
32a70 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65  ment was prepare
32a80 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65  d using the newe
32a90 72 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65  r "vX" interface
32aa0 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  s.** [sqlite3_pr
32ab0 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71  epare_v3()], [sq
32ac0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
32ad0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
32ae0 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2c 0a 2a  epare16_v3()],.*
32af0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
32b00 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68  re16_v2()] or th
32b10 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a  e older legacy.*
32b20 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
32b30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
32b40 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
32b50 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
32b60 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
32b70 65 77 20 22 76 58 22 20 69 6e 74 65 72 66 61 63  ew "vX" interfac
32b80 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
32b90 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
32ba0 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
32bb0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
32bc0 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
32bd0 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
32be0 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c  .**.** ^In the l
32bf0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
32c00 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
32c10 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72  e will be either
32c20 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a   [SQLITE_BUSY],.
32c30 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
32c40 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
32c50 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
32c60 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
32c70 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  E]..** ^With the
32c80 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
32c90 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
32ca0 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  r [result codes]
32cb0 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
32cc0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d   result codes] m
32cd0 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
32ce0 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20   as well..**.** 
32cf0 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d  ^[SQLITE_BUSY] m
32d00 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61  eans that the da
32d10 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61  tabase engine wa
32d20 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75  s unable to acqu
32d30 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ire the.** datab
32d40 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65  ase locks it nee
32d50 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62  ds to do its job
32d60 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65  .  ^If the state
32d70 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49  ment is a [COMMI
32d80 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  T].** or occurs 
32d90 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
32da0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
32db0 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
32dc0 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
32dd0 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
32de0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
32df0 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64  t a [COMMIT] and
32e00 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
32e10 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  n.** explicit tr
32e20 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79  ansaction then y
32e30 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61  ou should rollba
32e40 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
32e50 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e  on before.** con
32e60 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  tinuing..**.** ^
32e70 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
32e80 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
32e90 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
32ea0 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
32eb0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
32ec0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
32ed0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
32ee0 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
32ef0 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
32f00 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
32f10 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
32f20 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
32f30 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
32f40 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
32f50 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
32f60 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49   state..**.** ^I
32f70 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
32f80 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
32f90 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
32fa0 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ata, then [SQLIT
32fb0 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74  E_ROW].** is ret
32fc0 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
32fd0 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
32fe0 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70  a is ready for p
32ff0 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
33000 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  .** caller. The 
33010 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
33020 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65  cessed using the
33030 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
33040 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
33050 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
33060 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
33070 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
33080 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
33090 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45  **.** ^[SQLITE_E
330a0 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
330b0 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
330c0 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
330d0 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
330e0 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
330f0 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
33100 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
33110 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
33120 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
33130 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
33140 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
33150 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
33160 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69  rrmsg()]..** ^Wi
33170 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  th the legacy in
33180 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20  terface, a more 
33190 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
331a0 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ode (for example
331b0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  ,.** [SQLITE_INT
331c0 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
331d0 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
331e0 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
331f0 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
33200 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
33210 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
33220 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
33230 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
33240 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74  atement].  ^In t
33250 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
33260 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  e,.** the more s
33270 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
33280 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64  de is returned d
33290 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74  irectly by sqlit
332a0 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a  e3_step()..**.**
332b0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
332c0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
332d0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73  this routine was
332e0 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70   called inapprop
332f0 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68  riately..** Perh
33300 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65  aps it was calle
33310 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  d on a [prepared
33320 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
33330 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
33340 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
33350 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
33360 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
33370 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f  at had.** previo
33380 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53  usly returned [S
33390 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20  QLITE_ERROR] or 
333a0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
333b0 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62  Or it could.** b
333c0 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
333d0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
333e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
333f0 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77  being used by tw
33400 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72  o or.** more thr
33410 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
33420 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e   moment in time.
33430 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76  .**.** For all v
33440 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
33450 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c  e up to and incl
33460 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20  uding 3.6.23.1, 
33470 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
33480 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
33490 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65  as required afte
334a0 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  r sqlite3_step()
334b0 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69   returned anythi
334c0 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e  ng.** other than
334d0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65   [SQLITE_ROW] be
334e0 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75  fore any subsequ
334f0 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ent invocation o
33500 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  f.** sqlite3_ste
33510 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f  p().  Failure to
33520 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
33530 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73  red statement us
33540 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
33550 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20  _reset()] would 
33560 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51  result in an [SQ
33570 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74  LITE_MISUSE] ret
33580 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  urn from.** sqli
33590 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74  te3_step().  But
335a0 20 61 66 74 65 72 20 5b 76 65 72 73 69 6f 6e 20   after [version 
335b0 33 2e 36 2e 32 33 2e 31 5d 20 28 5b 64 61 74 65  3.6.23.1] ([date
335c0 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a 2a 2a  of:3.6.23.1],.**
335d0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
335e0 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67  began.** calling
335f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
33600 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  )] automatically
33610 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73   in this circums
33620 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20  tance rather.** 
33630 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b  than returning [
33640 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
33650 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e   This is not con
33660 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74  sidered a compat
33670 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b  ibility.** break
33680 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70   because any app
33690 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76  lication that ev
336a0 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53  er receives an S
336b0 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72  QLITE_MISUSE err
336c0 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20  or.** is broken 
336d0 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  by definition.  
336e0 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  The [SQLITE_OMIT
336f0 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70  _AUTORESET] comp
33700 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a  ile-time option.
33710 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ** can be used t
33720 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65  o restore the le
33730 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a  gacy behavior..*
33740 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e  *.** <b>Goofy In
33750 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f  terface Alert:</
33760 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  b> In the legacy
33770 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
33780 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a  sqlite3_step().*
33790 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74  * API always ret
337a0 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65  urns a generic e
337b0 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49  rror code, [SQLI
337c0 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
337d0 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f  wing any.** erro
337e0 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  r other than [SQ
337f0 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b  LITE_BUSY] and [
33800 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
33810 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a   You must call.*
33820 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
33830 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
33840 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
33850 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
33860 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69   of the.** speci
33870 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
33880 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
33890 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
338a0 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
338b0 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
338c0 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
338d0 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
338e0 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
338f0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
33900 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
33910 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
33920 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
33930 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
33940 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 6f  _prepare_v3()] o
33950 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
33960 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b  re_v2()].** or [
33970 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
33980 36 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  6_v2()] or [sqli
33990 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
339a0 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
339b0 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
339c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
339d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
339e0 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72  epare16()] inter
339f0 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  faces,.** then t
33a00 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
33a10 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61   [error codes] a
33a20 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
33a30 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
33a40 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
33a50 75 73 65 20 6f 66 20 74 68 65 20 22 76 58 22 20  use of the "vX" 
33a60 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 72 65  interfaces is re
33a70 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e  commended..*/.in
33a80 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73  t sqlite3_step(s
33a90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
33aa0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33ab0 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  Number of column
33ac0 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65  s in a result se
33ad0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
33ae0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
33af0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
33b00 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
33b10 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
33b20 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
33b30 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
33b40 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
33b50 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
33b60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33b70 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
33b80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
33b90 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
33ba0 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
33bb0 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
33bc0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
33bd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
33be0 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
33bf0 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
33c00 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
33c10 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
33c20 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
33c30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
33c40 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
33c50 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
33c60 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
33c70 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e  LL pointer..** ^
33c80 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
33c90 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
33ca0 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74  e returns 0 if t
33cb0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
33cc0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
33cd0 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
33ce0 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  d [SQLITE_DONE].
33cf0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64    ^The sqlite3_d
33d00 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20  ata_count(P).** 
33d10 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d  will return non-
33d20 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73  zero if previous
33d30 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
33d40 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
33d50 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  ned.** [SQLITE_R
33d60 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74  OW], except in t
33d70 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b  he case of the [
33d80 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74  PRAGMA increment
33d90 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68  al_vacuum].** wh
33da0 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65  ere it always re
33db0 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65  turns zero since
33dc0 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68   each step of th
33dd0 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a  at multi-step.**
33de0 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20   pragma returns 
33df0 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74  0 columns of dat
33e00 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  a..**.** See als
33e10 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
33e20 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  mn_count()].*/.i
33e30 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
33e40 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
33e50 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
33e60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
33e70 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
33e80 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
33e90 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
33ea0 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
33eb0 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
33ec0 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
33ed0 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
33ee0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
33ef0 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
33f00 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
33f10 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
33f20 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
33f30 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
33f40 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
33f50 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
33f60 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
33f70 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
33f80 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
33f90 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
33fa0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
33fb0 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
33fc0 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
33fd0 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
33fe0 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
33ff0 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
34000 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
34010 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
34020 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
34030 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
34040 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
34050 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
34060 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
34070 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
34080 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
34090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
340a0 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
340b0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
340c0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
340d0 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
340e0 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
340f0 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
34100 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
34110 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
34120 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
34130 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
34140 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
34150 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
34160 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34170 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
34180 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
34190 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
341a0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
341b0 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  s}.** METHOD: sq
341c0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
341d0 20 3c 62 3e 53 75 6d 6d 61 72 79 3a 3c 2f 62 3e   <b>Summary:</b>
341e0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
341f0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 30 20  <table border=0 
34200 63 65 6c 6c 70 61 64 64 69 6e 67 3d 30 20 63 65  cellpadding=0 ce
34210 6c 6c 73 70 61 63 69 6e 67 3d 30 3e 0a 2a 2a 20  llspacing=0>.** 
34220 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
34230 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 3c 2f  e3_column_blob</
34240 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
34250 42 4c 4f 42 20 72 65 73 75 6c 74 0a 2a 2a 20 3c  BLOB result.** <
34260 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
34270 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 3c  3_column_double<
34280 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
34290 3e 52 45 41 4c 20 72 65 73 75 6c 74 0a 2a 2a 20  >REAL result.** 
342a0 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
342b0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 3c 2f 62  e3_column_int</b
342c0 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 33  ><td>&rarr;<td>3
342d0 32 2d 62 69 74 20 49 4e 54 45 47 45 52 20 72 65  2-bit INTEGER re
342e0 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  sult.** <tr><td>
342f0 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
34300 6e 5f 69 6e 74 36 34 3c 2f 62 3e 3c 74 64 3e 26  n_int64</b><td>&
34310 72 61 72 72 3b 3c 74 64 3e 36 34 2d 62 69 74 20  rarr;<td>64-bit 
34320 49 4e 54 45 47 45 52 20 72 65 73 75 6c 74 0a 2a  INTEGER result.*
34330 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
34340 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
34350 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
34360 64 3e 55 54 46 2d 38 20 54 45 58 54 20 72 65 73  d>UTF-8 TEXT res
34370 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  ult.** <tr><td><
34380 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
34390 5f 74 65 78 74 31 36 3c 2f 62 3e 3c 74 64 3e 26  _text16</b><td>&
343a0 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d 31 36 20  rarr;<td>UTF-16 
343b0 54 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c  TEXT result.** <
343c0 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
343d0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 3c 2f  3_column_value</
343e0 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
343f0 54 68 65 20 72 65 73 75 6c 74 20 61 73 20 61 6e  The result as an
34400 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61   .** [sqlite3_va
34410 6c 75 65 7c 75 6e 70 72 6f 74 65 63 74 65 64 20  lue|unprotected 
34420 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
34430 62 6a 65 63 74 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  bject..** <tr><t
34440 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73  d>&nbsp;<td>&nbs
34450 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 0a 2a 2a 20  p;<td>&nbsp;.** 
34460 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
34470 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 3c  e3_column_bytes<
34480 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
34490 3e 53 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 0a  >Size of a BLOB.
344a0 2a 2a 20 6f 72 20 61 20 55 54 46 2d 38 20 54 45  ** or a UTF-8 TE
344b0 58 54 20 72 65 73 75 6c 74 20 69 6e 20 62 79 74  XT result in byt
344c0 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  es.** <tr><td><b
344d0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
344e0 62 79 74 65 73 31 36 26 6e 62 73 70 3b 26 6e 62  bytes16&nbsp;&nb
344f0 73 70 3b 3c 2f 62 3e 0a 2a 2a 20 3c 74 64 3e 26  sp;</b>.** <td>&
34500 72 61 72 72 3b 26 6e 62 73 70 3b 26 6e 62 73 70  rarr;&nbsp;&nbsp
34510 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 55 54 46  ;<td>Size of UTF
34520 2d 31 36 0a 2a 2a 20 54 45 58 54 20 69 6e 20 62  -16.** TEXT in b
34530 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ytes.** <tr><td>
34540 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
34550 6e 5f 74 79 70 65 3c 2f 62 3e 3c 74 64 3e 26 72  n_type</b><td>&r
34560 61 72 72 3b 3c 74 64 3e 44 65 66 61 75 6c 74 0a  arr;<td>Default.
34570 2a 2a 20 64 61 74 61 74 79 70 65 20 6f 66 20 74  ** datatype of t
34580 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 2f 74  he result.** </t
34590 61 62 6c 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  able></blockquot
345a0 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 44 65 74 61  e>.**.** <b>Deta
345b0 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 5e  ils:</b>.**.** ^
345c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
345d0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
345e0 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
345f0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
34600 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
34610 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
34620 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
34630 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
34640 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
34650 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
34660 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
34670 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
34680 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
34690 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
346a0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
346b0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
346c0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
346d0 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
346e0 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
346f0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
34700 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
34710 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
34720 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
34730 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
34740 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
34750 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
34760 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
34770 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
34780 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
34790 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
347a0 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
347b0 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
347c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
347d0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
347e0 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
347f0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
34800 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
34810 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
34820 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
34830 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
34840 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
34850 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
34860 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
34870 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
34880 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
34890 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
348a0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
348b0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
348c0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
348d0 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
348e0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
348f0 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
34900 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
34910 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
34920 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
34930 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
34940 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
34950 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
34960 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
34970 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
34980 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
34990 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
349a0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
349b0 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
349c0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
349d0 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
349e0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
349f0 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
34a00 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
34a10 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
34a20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
34a30 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
34a40 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
34a50 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
34a60 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
34a70 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
34a80 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
34a90 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
34aa0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
34ab0 20 66 69 72 73 74 20 73 69 78 20 69 6e 74 65 72   first six inter
34ac0 66 61 63 65 73 20 28 5f 62 6c 6f 62 2c 20 5f 64  faces (_blob, _d
34ad0 6f 75 62 6c 65 2c 20 5f 69 6e 74 2c 20 5f 69 6e  ouble, _int, _in
34ae0 74 36 34 2c 20 5f 74 65 78 74 2c 20 61 6e 64 20  t64, _text, and 
34af0 5f 74 65 78 74 31 36 29 0a 2a 2a 20 65 61 63 68  _text16).** each
34b00 20 72 65 74 75 72 6e 20 74 68 65 20 76 61 6c 75   return the valu
34b10 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
34b20 6c 75 6d 6e 20 69 6e 20 61 20 73 70 65 63 69 66  lumn in a specif
34b30 69 63 20 64 61 74 61 20 66 6f 72 6d 61 74 2e 20  ic data format. 
34b40 20 49 66 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c   If.** the resul
34b50 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 6f 74 20  t column is not 
34b60 69 6e 69 74 69 61 6c 6c 79 20 69 6e 20 74 68 65  initially in the
34b70 20 72 65 71 75 65 73 74 65 64 20 66 6f 72 6d 61   requested forma
34b80 74 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  t (for example,.
34b90 2a 2a 20 69 66 20 74 68 65 20 71 75 65 72 79 20  ** if the query 
34ba0 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
34bb0 65 72 20 62 75 74 20 74 68 65 20 73 71 6c 69 74  er but the sqlit
34bc0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
34bd0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73   interface.** is
34be0 20 75 73 65 64 20 74 6f 20 65 78 74 72 61 63 74   used to extract
34bf0 20 74 68 65 20 76 61 6c 75 65 29 20 74 68 65 6e   the value) then
34c00 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 74 79   an automatic ty
34c10 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  pe conversion is
34c20 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a   performed..**.*
34c30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
34c40 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
34c50 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
34c60 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
34c70 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
34c80 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
34c90 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
34ca0 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
34cb0 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65  column.  ^The re
34cc0 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20  turned value is 
34cd0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
34ce0 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  NTEGER],.** [SQL
34cf0 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
34d00 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49  ITE_TEXT], [SQLI
34d10 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51  TE_BLOB], or [SQ
34d20 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 0a 2a 2a 20 54  LITE_NULL]..** T
34d30 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
34d40 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
34d50 6e 5f 74 79 70 65 28 29 20 63 61 6e 20 62 65 20  n_type() can be 
34d60 75 73 65 64 20 74 6f 20 64 65 63 69 64 65 20 77  used to decide w
34d70 68 69 63 68 0a 2a 2a 20 6f 66 20 74 68 65 20 66  hich.** of the f
34d80 69 72 73 74 20 73 69 78 20 69 6e 74 65 72 66 61  irst six interfa
34d90 63 65 20 73 68 6f 75 6c 64 20 62 65 20 75 73 65  ce should be use
34da0 64 20 74 6f 20 65 78 74 72 61 63 74 20 74 68 65  d to extract the
34db0 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e 0a 2a   column value..*
34dc0 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75  * The value retu
34dd0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
34de0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
34df0 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
34e00 20 69 66 20 6e 6f 0a 2a 2a 20 61 75 74 6f 6d 61   if no.** automa
34e10 74 69 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73  tic type convers
34e20 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
34e30 65 64 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ed for the value
34e40 20 69 6e 20 71 75 65 73 74 69 6f 6e 2e 20 20 0a   in question.  .
34e50 2a 2a 20 41 66 74 65 72 20 61 20 74 79 70 65 20  ** After a type 
34e60 63 6f 6e 76 65 72 73 69 6f 6e 2c 20 74 68 65 20  conversion, the 
34e70 72 65 73 75 6c 74 20 6f 66 20 63 61 6c 6c 69 6e  result of callin
34e80 67 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  g sqlite3_column
34e90 5f 74 79 70 65 28 29 0a 2a 2a 20 69 73 20 75 6e  _type().** is un
34ea0 64 65 66 69 6e 65 64 2c 20 74 68 6f 75 67 68 20  defined, though 
34eb0 68 61 72 6d 6c 65 73 73 2e 20 20 46 75 74 75 72  harmless.  Futur
34ec0 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
34ed0 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
34ee0 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
34ef0 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
34f00 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
34f10 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
34f20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  version..**.** I
34f30 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
34f40 61 20 42 4c 4f 42 20 6f 72 20 61 20 54 45 58 54  a BLOB or a TEXT
34f50 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 74 68   string, then th
34f60 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
34f70 5f 62 79 74 65 73 28 29 0a 2a 2a 20 6f 72 20 73  _bytes().** or s
34f80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
34f90 74 65 73 31 36 28 29 20 69 6e 74 65 72 66 61 63  tes16() interfac
34fa0 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
34fb0 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
34fc0 73 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 61 74 20  size.** of that 
34fd0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
34fe0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
34ff0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
35000 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
35010 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
35020 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
35030 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
35040 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
35050 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
35060 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
35070 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
35080 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
35090 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
350a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
350b0 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
350c0 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
350d0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
350e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
350f0 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
35100 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
35110 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
35120 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
35130 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
35140 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
35150 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
35160 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
35170 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
35180 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
35190 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
351a0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
351b0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
351c0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
351d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
351e0 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65  tes() returns ze
351f0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ro..**.** ^If th
35200 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
35210 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  OB or UTF-16 str
35220 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
35230 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35240 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  s16().** routine
35250 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
35260 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
35270 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
35280 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
35290 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
352a0 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  8 string, then s
352b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
352c0 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73  tes16() converts
352d0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
352e0 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65  o UTF-16 and the
352f0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
35300 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
35310 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
35320 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
35330 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
35340 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
35350 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
35360 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
35370 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
35380 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36  alue to a UTF-16
35390 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
353a0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
353b0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
353c0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
353d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
353e0 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
353f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
35400 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  6() returns zero
35410 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ..**.** ^The val
35420 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
35430 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
35440 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a  bytes()] and .**
35450 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
35460 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e  _bytes16()] do n
35470 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
35480 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20  ero terminators 
35490 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
354a0 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
354b0 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
354c0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
354d0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
354e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
354f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
35500 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72  mn_bytes16()] ar
35510 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  e the number of.
35520 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
35530 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
35540 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
35550 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
35560 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
35570 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35580 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
35590 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
355a0 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
355b0 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
355c0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
355d0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
355e0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
355f0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
35600 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
35610 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
35620 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
35630 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69  ..**.** <b>Warni
35640 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a  ng:</b> ^The obj
35650 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
35660 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
35670 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
35680 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
35690 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
356a0 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74  ject.  In a mult
356b0 69 74 68 72 65 61 64 65 64 20 65 6e 76 69 72 6f  ithreaded enviro
356c0 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70  nment,.** an unp
356d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
356e0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
356f0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 73  y only be used s
35700 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73  afely with.** [s
35710 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
35720 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
35730 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
35740 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
35750 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
35760 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
35770 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
35780 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
35790 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
357a0 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
357b0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
357c0 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
357d0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
357e0 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
357f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
35800 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
35810 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
35820 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  )], the behavior
35830 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
35840 66 65 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 74 68  fe..** Hence, th
35850 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
35860 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
35870 63 65 0a 2a 2a 20 69 73 20 6e 6f 72 6d 61 6c 6c  ce.** is normall
35880 79 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 77 69  y only useful wi
35890 74 68 69 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65  thin the impleme
358a0 6e 74 61 74 69 6f 6e 20 6f 66 20 0a 2a 2a 20 5b  ntation of .** [
358b0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
358c0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
358d0 73 5d 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74  s] or [virtual t
358e0 61 62 6c 65 73 5d 2c 20 6e 6f 74 20 77 69 74 68  ables], not with
358f0 69 6e 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  in.** top-level 
35900 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
35910 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 65 73  ..**.** The thes
35920 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 61  e routines may a
35930 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
35940 74 20 74 68 65 20 64 61 74 61 74 79 70 65 20 6f  t the datatype o
35950 66 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a  f the result..**
35960 20 5e 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69   ^For example, i
35970 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
35980 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
35990 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
359a0 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
359b0 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
359c0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
359d0 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
359e0 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
359f0 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
35a00 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
35a10 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
35a20 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
35a30 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
35a40 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
35a50 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
35a60 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
35a70 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
35a80 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
35a90 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
35aa0 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
35ab0 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
35ac0 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
35ad0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
35ae0 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
35af0 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
35b00 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
35b10 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
35b20 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
35b30 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
35b40 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
35b50 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
35b60 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
35b70 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
35b80 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
35b90 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
35ba0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
35bb0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
35bc0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
35bd0 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
35be0 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
35bf0 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
35c00 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
35c10 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
35c20 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
35c30 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
35c40 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
35c50 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
35c60 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
35c70 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  as INTEGER->TEXT
35c80 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
35c90 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
35ca0 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
35cb0 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
35cc0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
35cd0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
35ce0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
35cf0 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
35d00 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
35d10 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
35d20 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  OB    <td> [CAST
35d30 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72  ] to BLOB.** <tr
35d40 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
35d50 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
35d60 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
35d70 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
35d80 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
35d90 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43  FLOAT    <td> [C
35da0 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20  AST] to REAL.** 
35db0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
35dc0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
35dd0 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
35de0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
35df0 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
35e00 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
35e10 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
35e20 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
35e30 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
35e40 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45  td> [CAST] to RE
35e50 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  AL.** <tr><td>  
35e60 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
35e70 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
35e80 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
35e90 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
35ea0 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
35eb0 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
35ec0 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
35ed0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
35ee0 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
35ef0 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
35f00 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
35f10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
35f20 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
35f30 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
35f40 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
35f50 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
35f60 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
35f70 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
35f80 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
35f90 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
35fa0 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
35fb0 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
35fc0 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
35fd0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
35fe0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
35ff0 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
36000 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
36010 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
36020 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
36030 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
36040 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
36050 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
36060 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
36070 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
36080 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
36090 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
360a0 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
360b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
360c0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
360d0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
360e0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
360f0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
36100 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
36110 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
36120 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
36130 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
36140 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
36150 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
36160 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
36170 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
36180 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
36190 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
361a0 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
361b0 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
361c0 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
361d0 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
361e0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
361f0 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
36200 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
36210 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
36220 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
36230 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
36240 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
36250 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
36260 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
36270 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
36280 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
36290 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
362a0 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
362b0 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
362c0 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
362d0 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
362e0 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
362f0 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
36300 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
36310 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
36320 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
36330 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
36340 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
36350 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
36360 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
36370 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
36380 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
36390 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
363a0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
363b0 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
363c0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
363d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
363e0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
363f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
36400 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
36410 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
36420 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
36430 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36440 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
36450 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
36460 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
36470 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
36480 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
36490 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
364a0 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
364b0 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
364c0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
364d0 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
364e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
364f0 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
36500 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
36510 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
36520 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
36530 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
36540 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
36550 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
36560 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
36570 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36580 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
36590 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
365a0 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
365b0 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
365c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
365d0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
365e0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
365f0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
36600 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36610 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
36620 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
36630 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
36640 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
36650 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
36660 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
36670 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ()..**.** ^The p
36680 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
36690 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
366a0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
366b0 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
366c0 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
366d0 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
366e0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
366f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
36700 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
36710 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
36720 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f  lled.  ^The memo
36730 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
36740 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
36750 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
36760 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
36770 79 2e 20 20 44 6f 20 6e 6f 74 20 70 61 73 73 20  y.  Do not pass 
36780 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  the pointers ret
36790 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
367a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
367b0 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
367c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
367d0 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71  etc. into.** [sq
367e0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
367f0 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f  *.** ^(If a memo
36800 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
36810 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
36820 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e  g the evaluation
36830 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
36840 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20  ese routines, a 
36850 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73  default value is
36860 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
36870 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a  default value.**
36880 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69   is either the i
36890 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c  nteger 0, the fl
368a0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
368b0 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55  ber 0.0, or a NU
368c0 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20  LL.** pointer.  
368d0 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  Subsequent calls
368e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
368f0 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74  code()] will ret
36900 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  urn.** [SQLITE_N
36910 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73  OMEM].)^.*/.cons
36920 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
36930 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
36940 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
36950 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  Col);.double sql
36960 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
36970 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
36980 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
36990 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
369a0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
369b0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
369c0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
369d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
369e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
369f0 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
36a00 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
36a10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
36a20 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
36a30 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
36a40 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
36a50 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
36a60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
36a70 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
36a80 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33  3_value *sqlite3
36a90 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71  _column_value(sq
36aa0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
36ab0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
36ac0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
36ad0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
36ae0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
36af0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
36b00 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
36b10 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
36b20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
36b30 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
36b40 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
36b50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36b60 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
36b70 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
36b80 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55  Object.** DESTRU
36b90 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74  CTOR: sqlite3_st
36ba0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
36bb0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
36bc0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
36bd0 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
36be0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
36bf0 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ent]..** ^If the
36c00 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
36c10 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  luation of the s
36c20 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74  tatement encount
36c30 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a  ered no errors.*
36c40 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74  * or if the stat
36c50 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62  ement is never b
36c60 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74  een evaluated, t
36c70 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  hen sqlite3_fina
36c80 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a  lize() returns.*
36c90 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49  * SQLITE_OK.  ^I
36ca0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
36cb0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
36cc0 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c  statement S fail
36cd0 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ed, then.** sqli
36ce0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
36cf0 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72  returns the appr
36d00 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
36d10 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
36d20 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
36d30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36d40 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
36d50 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
36d60 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
36d70 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68  int during.** th
36d80 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20  e life cycle of 
36d90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
36da0 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72  ent] S:.** befor
36db0 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  e statement S is
36dc0 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c   ever evaluated,
36dd0 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72   after.** one or
36de0 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b   more calls to [
36df0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
36e00 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63  , or after any c
36e10 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  all.** to [sqlit
36e20 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72  e3_step()] regar
36e30 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
36e40 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74   or not the stat
36e50 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d  ement has.** com
36e60 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
36e70 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e  ..**.** ^Invokin
36e80 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  g sqlite3_finali
36e90 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70  ze() on a NULL p
36ea0 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d  ointer is a harm
36eb0 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
36ec0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
36ed0 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20  n must finalize 
36ee0 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20  every [prepared 
36ef0 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72  statement] in or
36f00 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  der to avoid.** 
36f10 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20  resource leaks. 
36f20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75   It is a grievou
36f30 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20  s error for the 
36f40 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74  application to t
36f50 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70  ry to use.** a p
36f60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36f70 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
36f80 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20  een finalized.  
36f90 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65  Any use of a pre
36fa0 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
36fb0 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
36fc0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63  been finalized c
36fd0 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  an result in und
36fe0 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e  efined and.** un
36ff0 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
37000 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61  or such as segfa
37010 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f  ults and heap co
37020 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74  rruption..*/.int
37030 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
37040 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
37050 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
37060 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
37070 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
37080 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45  ent Object.** ME
37090 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
370a0 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  mt.**.** The sql
370b0 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
370c0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
370d0 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
370e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
370f0 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
37100 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
37110 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
37120 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
37130 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d   ^Any SQL statem
37140 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68  ent variables th
37150 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f  at had values bo
37160 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e  und to them usin
37170 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
37180 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
37190 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41  lite3_bind_*() A
371a0 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72  PI] retain their
371b0 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20   values..** Use 
371c0 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
371d0 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65  indings()] to re
371e0 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73  set the bindings
371f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
37200 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
37210 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
37220 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
37230 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62  tatement] S.** b
37240 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
37250 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
37260 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ram..**.** ^If t
37270 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
37280 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
37290 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
372a0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
372b0 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
372c0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
372d0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
372e0 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c  ],.** or if [sql
372f0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
37300 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
37310 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
37320 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  .** then [sqlite
37330 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
37340 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
37350 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
37360 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
37370 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
37380 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
37390 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
373a0 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
373b0 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
373c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
373d0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
373e0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
373f0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
37400 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
37410 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
37420 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
37430 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
37440 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
37450 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
37460 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65  ngs] on the [pre
37470 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
37480 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74   S..*/.int sqlit
37490 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33  e3_reset(sqlite3
374a0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
374b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
374c0 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69  Create Or Redefi
374d0 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73  ne SQL Functions
374e0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
374f0 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
37500 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
37510 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
37520 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
37530 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
37540 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
37550 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
37560 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d   functions}.** M
37570 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
37580 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
37590 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
375a0 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
375b0 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
375c0 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
375d0 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
375e0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
375f0 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
37600 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
37610 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
37620 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
37630 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
37640 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
37650 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a  erences between.
37660 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ** these routine
37670 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65  s are the text e
37680 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64  ncoding expected
37690 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f   for.** the seco
376a0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  nd parameter (th
376b0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75  e name of the fu
376c0 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65  nction being cre
376d0 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ated).** and the
376e0 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73   presence or abs
376f0 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75  ence of a destru
37700 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f  ctor callback fo
37710 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  r.** the applica
37720 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
37730 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  r..**.** ^The fi
37740 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
37750 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
37760 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
37770 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
37780 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
37790 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20   added.  ^If an 
377a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73  application uses
377b0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
377c0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
377d0 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69  ction then appli
377e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
377f0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
37800 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f  t be added.** to
37810 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
37820 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61  onnection separa
37830 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tely..**.** ^The
37840 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
37850 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
37860 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
37870 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20  n to be created 
37880 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e  or.** redefined.
37890 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66    ^The length of
378a0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
378b0 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
378c0 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20  s in a UTF-8.** 
378d0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20  representation, 
378e0 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
378f0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
37900 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  .  ^Note that th
37910 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68  e name.** length
37920 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46   limit is in UTF
37930 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68  -8 bytes, not ch
37940 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46  aracters nor UTF
37950 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20  -16 bytes.  .** 
37960 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20  ^Any attempt to 
37970 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
37980 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
37990 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
379a0 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d  ult in [SQLITE_M
379b0 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74  ISUSE] being ret
379c0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
379d0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
379e0 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74  r (nArg).** is t
379f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
37a00 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
37a10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
37a20 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
37a30 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72  es. ^If this par
37a40 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68  ameter is -1, th
37a50 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
37a60 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
37a70 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
37a80 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
37a90 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61  ents between 0 a
37aa0 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20  nd the limit.** 
37ab0 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  set by [sqlite3_
37ac0 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
37ad0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
37ae0 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69  G]).  If the thi
37af0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
37b00 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20  is less than -1 
37b10 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
37b20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68  127 then the beh
37b30 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65  avior is.** unde
37b40 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
37b50 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
37b60 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
37b70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
37b80 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
37b90 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
37ba0 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
37bb0 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
37bc0 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
37bd0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
37be0 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20  should set this 
37bf0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
37c00 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
37c10 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   if the function
37c20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
37c30 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c  invokes .** [sql
37c40 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
37c50 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70  6le()] on an inp
37c60 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ut, or [SQLITE_U
37c70 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a  TF16BE] if the.*
37c80 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
37c90 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65   invokes [sqlite
37ca0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
37cb0 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c  ()] on an input,
37cc0 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   or.** [SQLITE_U
37cd0 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65  TF16] if [sqlite
37ce0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
37cf0 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53  ] is used, or [S
37d00 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f  QLITE_UTF8].** o
37d10 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20  therwise.  ^The 
37d20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
37d30 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
37d40 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  red multiple tim
37d50 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66  es using.** diff
37d60 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 64 20  erent preferred 
37d70 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20  text encodings, 
37d80 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 69  with different i
37d90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
37da0 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64  or.** each encod
37db0 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75  ing..** ^When mu
37dc0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
37dd0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
37de0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  me function are 
37df0 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74  available, SQLit
37e00 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74  e.** will pick t
37e10 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f  he one that invo
37e20 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  lves the least a
37e30 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f  mount of data co
37e40 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
37e50 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
37e60 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e  meter may option
37e70 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74  ally be ORed wit
37e80 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d  h [SQLITE_DETERM
37e90 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73  INISTIC].** to s
37ea0 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66  ignal that the f
37eb0 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77  unction will alw
37ec0 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73  ays return the s
37ed0 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e  ame result given
37ee0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70  .** the same inp
37ef0 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e  uts within a sin
37f00 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
37f10 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e  t.  Most SQL fun
37f20 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65  ctions are.** de
37f30 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68  terministic.  Th
37f40 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64  e built-in [rand
37f50 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69  om()] SQL functi
37f60 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65  on is an example
37f70 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   of a.** functio
37f80 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65  n that is not de
37f90 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68  terministic.  Th
37fa0 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 20 70  e SQLite query p
37fb0 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74  lanner is able t
37fc0 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64  o.** perform add
37fd0 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61  itional optimiza
37fe0 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69  tions on determi
37ff0 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73  nistic functions
38000 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74  , so use.** of t
38010 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52  he [SQLITE_DETER
38020 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69  MINISTIC] flag i
38030 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68  s recommended wh
38040 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a  ere possible..**
38050 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20  .** ^(The fifth 
38060 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
38070 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
38080 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
38090 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
380a0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
380b0 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
380c0 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
380d0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
380e0 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ta()].)^.**.** ^
380f0 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e  The sixth, seven
38100 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61  th and eighth pa
38110 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
38120 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
38130 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
38140 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
38150 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
38160 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
38170 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
38180 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73   aggregate. ^A s
38190 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
381a0 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
381b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
381c0 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
381d0 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c  llback only; NUL
381e0 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20  L pointers must 
381f0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
38200 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
38210 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
38220 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53   ^An aggregate S
38230 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
38240 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
38250 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
38260 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
38270 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d  d NULL pointer m
38280 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f  ust be passed fo
38290 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
382a0 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
382b0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
382c0 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
382d0 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  ss NULL pointers
382e0 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
382f0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
38300 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  acks..**.** ^(If
38310 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d   the ninth param
38320 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
38330 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
38340 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  v2() is not NULL
38350 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
38360 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
38370 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
38380 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a  ata pointer. .**
38390 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
383a0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
383b0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
383c0 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20  deleted, either 
383d0 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72  by being.** over
383e0 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74  loaded or when t
383f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
38400 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e  ection closes.)^
38410 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63  .** ^The destruc
38420 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f  tor is also invo
38430 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ked if the call 
38440 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  to.** sqlite3_cr
38450 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
38460 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68  () fails..** ^Wh
38470 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  en the destructo
38480 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  r callback of th
38490 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65  e tenth paramete
384a0 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  r is invoked, it
384b0 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20  .** is passed a 
384c0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
384d0 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20  which is a copy 
384e0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
384f0 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e  on data .** poin
38500 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68  ter which was th
38510 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
38520 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
38530 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
38540 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  )..**.** ^It is 
38550 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
38560 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
38570 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
38580 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
38590 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
385a0 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
385b0 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
385c0 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
385d0 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
385e0 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
385f0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
38600 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
38610 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
38620 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
38630 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
38640 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
38650 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
38660 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
38670 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  ed.  ^A function
38680 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
38690 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
386a0 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
386b0 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
386c0 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
386d0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
386e0 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
386f0 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
38700 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
38710 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
38720 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
38730 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
38740 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase