/ Hex Artifact Content
Login

Artifact 6178cd914ca32535015ff57df78438f87a0f16609e9e47b1bc5f373ffe892686:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
10c0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
10d0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
10e0: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
10f0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1100: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
1110: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
1120: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
1130: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
1140: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
1150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1160: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
1170: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1180: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1190: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
11a0: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
11b0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
11c0: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
11d0: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
11e0: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
11f0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1200: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1210: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
1220: 65 72 73 69 6f 6e 20 73 71 6c 69 74 65 33 5f 73  ersion sqlite3_s
1230: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
1240: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
1250: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
1260: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
1270: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1280: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1290: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
12a0: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
12b0: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
12c0: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
12d0: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
12e0: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
12f0: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
1300: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
1310: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
1320: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
1330: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
1340: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
1350: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
1360: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
1370: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1380: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1390: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
13a0: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
13b0: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
13c0: 74 68 75 73 20 65 6e 73 75 72 65 20 74 68 61 74  thus ensure that
13d0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
13e0: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
13f0: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
1400: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
1410: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
1420: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1430: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
1440: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1450: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
1460: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
1470: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1480: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  mp(sqlite3_sourc
1490: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55  eid(),SQLITE_SOU
14a0: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a  RCE_ID)==0 );.**
14b0: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
14c0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
14d0: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53  on(),SQLITE_VERS
14e0: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f  ION)==0 );.** </
14f0: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1500: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1510: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1520: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1530: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
1540: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45  xt of [SQLITE_VE
1550: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e  RSION].** macro.
1560: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c    ^The sqlite3_l
1570: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
1580: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70  tion returns a p
1590: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
15a0: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
15b0: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
15c0: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
15d0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
15e0: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  on().** function
15f0: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
1600: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1610: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
1620: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
1630: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73  .** direct acces
1640: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73  s to string cons
1650: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
1660: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73   DLL.  ^The.** s
1670: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1680: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74  n_number() funct
1690: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ion returns an i
16a0: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a  nteger equal to.
16b0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
16c0: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68  ON_NUMBER].  ^Th
16d0: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  e sqlite3_source
16e0: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  id() function re
16f0: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  turns .** a poin
1700: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
1710: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76  constant whose v
1720: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65  alue is the same
1730: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c   as the .** [SQL
1740: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
1750: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1760: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  cro..**.** See a
1770: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
1780: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
1790: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
17a0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
17b0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
17c0: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
17d0: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
17e0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
17f0: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1800: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1810: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1820: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1830: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1840: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1850: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
1860: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
1870: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
1880: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1890: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
18a0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
18b0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
18c0: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
18d0: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
18e0: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
18f0: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1900: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1910: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1920: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1930: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1940: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1950: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1960: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1970: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1980: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1990: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
19a0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
19b0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
19c0: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
19d0: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
19e0: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
19f0: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1a00: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1a10: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1a20: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1a30: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1a40: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1a60: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1a70: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1a80: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1a90: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1aa0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1ab0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1ac0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1ad0: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1ae0: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1af0: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1b00: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1b10: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1b20: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1b30: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1b40: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1b50: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1b60: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1b70: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1b80: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1b90: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ba0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1bb0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1bc0: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1bd0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1be0: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1bf0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1c00: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1c10: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1c20: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1c30: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1c40: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1c50: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1c60: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c70: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1c80: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1c90: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1ca0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1cb0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1cc0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1cd0: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1ce0: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1cf0: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1d00: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1d10: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1d20: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1d30: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1d40: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1d50: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1d60: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1d70: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1d80: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d90: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1da0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1db0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1dc0: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1dd0: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1de0: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1df0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1e00: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1e10: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1e20: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1e30: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1e40: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1e50: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1e60: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1e70: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1e80: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1e90: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1ea0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1eb0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
1ec0: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
1ed0: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
1ee0: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
1ef0: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
1f00: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
1f10: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
1f20: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
1f30: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
1f40: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
1f50: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
1f60: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
1f70: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
1f80: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
1f90: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
1fa0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
1fb0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
1fc0: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
1fd0: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
1fe0: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
1ff0: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2000: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2010: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2020: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2030: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
2040: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
2050: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
2060: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
2070: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
2080: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
2090: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
20a0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
20b0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
20c0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
20d0: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
20e0: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
20f0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2100: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2110: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2120: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2130: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2140: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
2150: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
2160: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
2170: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
2180: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
2190: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
21a0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
21b0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
21c0: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
21d0: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
21e0: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
21f0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2200: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2210: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2220: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2230: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
2240: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
2250: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
2260: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
2270: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
2280: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
2290: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
22a0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
22b0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
22c0: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
22d0: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
22e0: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
22f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2300: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2310: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2320: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2330: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2340: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2350: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2360: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
2370: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
2380: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
2390: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
23a0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
23b0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
23c0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
23d0: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
23e0: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
23f0: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2400: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2410: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2420: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2430: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2440: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2450: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
2460: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
2470: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
2480: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
2490: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
24a0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
24b0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
24c0: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
24d0: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
24e0: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
24f0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2500: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2510: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2520: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2530: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2540: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2550: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
2560: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
2570: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
2580: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
2590: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
25a0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
25b0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
25c0: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
25d0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
25e0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
25f0: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2600: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2610: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2620: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2630: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2640: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2650: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
2660: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2670: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
2680: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
2690: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
26a0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
26b0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
26c0: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
26d0: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
26e0: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
26f0: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2700: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2710: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2720: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2730: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2740: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2750: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
2760: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
2770: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
2780: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
2790: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
27a0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
27b0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
27c0: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
27d0: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
27e0: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
27f0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2800: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2810: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2820: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2830: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2840: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2850: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
2860: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
2870: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
2880: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
2890: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
28a0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
28b0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
28c0: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
28d0: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
28e0: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
28f0: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2900: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2910: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2920: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2930: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2940: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2950: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2960: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45  ;.# ifdef SQLITE
2970: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20  _UINT64_TYPE.   
2980: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2990: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  UINT64_TYPE sqli
29a0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73  te_uint64;.# els
29b0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20  e  .    typedef 
29c0: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
29d0: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
29e0: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69  e_uint64;.# endi
29f0: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  f.#elif defined(
2a00: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2a10: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2a20: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2a30: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2a40: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2a50: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2a60: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2a70: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2a80: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2a90: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2aa0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2ab0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2ac0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2ad0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2ae0: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2af0: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2b00: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2b10: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2b20: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2b30: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2b40: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2b50: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2b60: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2b70: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2b80: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2b90: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2ba0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2bb0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2bc0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2bd0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2be0: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2bf0: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2c00: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2c10: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2c20: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2c30: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2c40: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2c50: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2c60: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2c70: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2c80: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2c90: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2ca0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2cb0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2cc0: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2cd0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2ce0: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2cf0: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2d00: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2d10: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2d20: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2d30: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2d40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d50: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2d60: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2d70: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2d80: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2d90: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2da0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2db0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2dc0: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2dd0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2de0: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2df0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2e00: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2e10: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2e20: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2e30: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2e40: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2e50: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2e60: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2e70: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2e80: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2e90: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2ea0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2eb0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
2ec0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
2ed0: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
2ee0: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
2ef0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2f00: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
2f10: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
2f20: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
2f30: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
2f40: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
2f50: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
2f60: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
2f70: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
2f80: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
2f90: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
2fa0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
2fb0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
2fc0: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
2fd0: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
2fe0: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
2ff0: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3000: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3010: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
3020: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3030: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3040: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3050: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
3060: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
3070: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
3080: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
3090: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
30a0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
30b0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
30c0: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
30d0: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
30e0: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
30f0: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3100: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3110: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3120: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3130: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3140: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3150: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
3160: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3170: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
3180: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
3190: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
31a0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
31b0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
31c0: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
31d0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
31e0: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
31f0: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3200: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3210: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3220: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3230: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3240: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3250: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
3260: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
3270: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
3280: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
3290: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
32a0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
32b0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
32c0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
32d0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
32e0: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
32f0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3300: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3310: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3320: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3330: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3340: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3350: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
3360: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3370: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
3380: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
3390: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
33a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
33b0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
33c0: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
33d0: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
33e0: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
33f0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3400: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3410: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3420: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3430: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3440: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3450: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
3460: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
3470: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
3480: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
3490: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
34a0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
34b0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
34c0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
34d0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
34e0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
34f0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3500: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3510: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3520: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3530: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3540: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3550: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
3560: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
3570: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
3580: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
3590: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
35a0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
35b0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
35c0: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
35d0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
35e0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
35f0: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3600: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3610: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
3620: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
3630: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
3640: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
3650: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
3660: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
3670: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
3680: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
3690: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
36a0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
36b0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
36c0: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
36d0: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
36e0: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
36f0: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
3700: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
3710: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
3720: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3730: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
3740: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
3750: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
3760: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
3770: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
3780: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
3790: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
37a0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
37b0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
37c0: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
37d0: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
37e0: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
37f0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3800: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3810: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3820: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
3830: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3840: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
3850: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
3860: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
3870: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
3880: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
3890: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
38a0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
38b0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
38c0: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
38d0: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
38e0: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
38f0: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3900: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
3910: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
3920: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3930: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3940: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
3950: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3960: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3970: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3980: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3990: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
39a0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
39b0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
39c0: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
39d0: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
39e0: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
39f0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3a00: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
3a10: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3a20: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
3a30: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
3a40: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
3a50: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3a60: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3a70: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3a80: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3a90: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3aa0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3ab0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3ac0: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3ad0: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3ae0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3af0: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3b00: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3b10: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3b20: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3b30: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3b40: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3b50: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3b60: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3b70: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3b80: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3b90: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3ba0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3bb0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3bc0: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3bd0: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3be0: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3bf0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3c00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3c10: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3c20: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3c30: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3c40: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3c50: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3c60: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3c70: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3c80: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3c90: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3ca0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3cb0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3cc0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3cd0: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3ce0: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3cf0: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3d00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3d10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3d20: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3d30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3d40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3d50: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3d60: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3d70: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3d80: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3d90: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3da0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3db0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3dc0: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3dd0: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3de0: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3df0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3e00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3e10: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3e20: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3e30: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3e40: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3e50: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3e60: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3e70: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3e80: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3e90: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3ea0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3eb0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
3ec0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3ed0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
3ee0: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
3ef0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3f00: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3f10: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
3f20: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
3f30: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
3f40: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
3f50: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
3f60: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
3f70: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
3f80: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
3f90: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
3fa0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
3fb0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
3fc0: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
3fd0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
3fe0: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
3ff0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
4000: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4010: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
4020: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
4030: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
4040: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
4050: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
4060: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
4070: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
4080: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4090: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
40a0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
40b0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
40c0: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
40d0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
40e0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
40f0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4100: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4110: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4120: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4130: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
4140: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
4150: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
4160: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
4170: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
4180: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
4190: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
41a0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
41b0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
41c0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
41d0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41f0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4200: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4210: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4230: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4240: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4250: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
4260: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
4270: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
4280: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
4290: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42c0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
42d0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
42e0: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
42f0: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4310: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4320: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4330: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4340: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4350: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4360: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
4370: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
4380: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
4390: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
43a0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
43b0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
43c0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
43d0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
43e0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
43f0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4400: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4410: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4420: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4430: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4440: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4450: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
4460: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
4470: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
4480: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
4490: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
44a0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
44b0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
44c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
44d0: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
44e0: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72  /* Generic error
44f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4500: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4510: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4520: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4530: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4540: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4550: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
4560: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
4570: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4580: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
4590: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
45a0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
45b0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
45c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45d0: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
45e0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
45f0: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4600: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4610: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4620: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4630: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4640: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4650: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
4660: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
4670: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
4680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4690: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
46a0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
46b0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
46c0: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
46d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
46e0: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
46f0: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4700: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4710: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4720: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4730: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4740: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4750: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
4760: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
4770: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
4780: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
4790: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
47a0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
47b0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
47c0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
47d0: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
47e0: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
47f0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4800: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4810: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4820: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4830: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4840: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4850: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
4860: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
4870: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
4880: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
4890: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
48a0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
48b0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
48c0: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
48d0: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
48e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
48f0: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4900: 2a 20 4e 6f 74 20 75 73 65 64 20 2a 2f 0a 23 64  * Not used */.#d
4910: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
4920: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
4930: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
4940: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
4950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
4960: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
4970: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
4980: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
4990: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
49a0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
49b0: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
49c0: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
49d0: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
49e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
49f0: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
4a00: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
4a10: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
4a20: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
4a30: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
4a40: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
4a50: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
4a60: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
4a70: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
4a80: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
4a90: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
4aa0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4ab0: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
4ac0: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
4ad0: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
4ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4af0: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
4b00: 2f 2a 20 4e 6f 74 20 75 73 65 64 20 2a 2f 0a 23  /* Not used */.#
4b10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41  define SQLITE_RA
4b20: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f  NGE       25   /
4b30: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
4b40: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20  to sqlite3_bind 
4b50: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a  out of range */.
4b60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4b70: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20  OTADB      26   
4b80: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74  /* File opened t
4b90: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74  hat is not a dat
4ba0: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
4bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4bc0: 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a  ICE      27   /*
4bd0: 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66   Notifications f
4be0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4bf0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4c00: 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20  ITE_WARNING     
4c10: 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73  28   /* Warnings
4c20: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f   from sqlite3_lo
4c30: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  g() */.#define S
4c40: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4c50: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4c60: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4c70: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4c80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4c90: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4ca0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4cb0: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4cc0: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4cd0: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4ce0: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4cf0: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4d00: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4d10: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4d20: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4d30: 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a   definitions}.**
4d40: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
4d50: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
4d60: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
4d70: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
4d80: 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a   of 30 integer.*
4d90: 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  * [result codes]
4da0: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4db0: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4dc0: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
4dd0: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4de0: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
4df0: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
4e00: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
4e10: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
4e20: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
4e30: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
4e40: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
4e50: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4e60: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4e70: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4e80: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4e90: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 5b 64 61 74  rsion 3.3.8 [dat
4ea0: 65 6f 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20 61 6e  eof:3.3.8].** an
4eb0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
4ec0: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
4ed0: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
4ee0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
4ef0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4f00: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
4f10: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
4f20: 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20  These [extended 
4f30: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72  result codes] ar
4f40: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
4f50: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
4f60: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
4f70: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
4f80: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
4f90: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
4fa0: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20  t_codes()] API. 
4fb0: 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65   Or, the extende
4fc0: 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68  d code for.** th
4fd0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72  e most recent er
4fe0: 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69  ror can be obtai
4ff0: 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
5000: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
5010: 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64  rrcode()]..*/.#d
5020: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5030: 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  RR_READ         
5040: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5050: 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  RR | (1<<8)).#de
5060: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5070: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20  R_SHORT_READ    
5080: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5090: 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  R | (2<<8)).#def
50a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
50b0: 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  _WRITE          
50c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
50d0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
50e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
50f0: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  FSYNC           
5100: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5110: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
5120: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
5130: 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  IR_FSYNC        
5140: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5150: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5160: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52   SQLITE_IOERR_TR
5170: 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20  UNCATE          
5180: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5190: 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (6<<8)).#define 
51a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54  SQLITE_IOERR_FST
51b0: 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28  AT             (
51c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
51d0: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
51e0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f  QLITE_IOERR_UNLO
51f0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
5200: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38  QLITE_IOERR | (8
5210: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5220: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43  LITE_IOERR_RDLOC
5230: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
5240: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c  LITE_IOERR | (9<
5250: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5260: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
5270: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5280: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c  ITE_IOERR | (10<
5290: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
52a0: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
52b0: 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  D           (SQL
52c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c  ITE_IOERR | (11<
52d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
52e0: 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20  ITE_IOERR_NOMEM 
52f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5300: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c  ITE_IOERR | (12<
5310: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5320: 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53  ITE_IOERR_ACCESS
5330: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5340: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c  ITE_IOERR | (13<
5350: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5360: 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52  ITE_IOERR_CHECKR
5370: 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c  ESERVEDLOCK (SQL
5380: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c  ITE_IOERR | (14<
5390: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
53a0: 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20  ITE_IOERR_LOCK  
53b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
53c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c  ITE_IOERR | (15<
53d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
53e0: 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20  ITE_IOERR_CLOSE 
53f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5400: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c  ITE_IOERR | (16<
5410: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5420: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c  ITE_IOERR_DIR_CL
5430: 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c  OSE         (SQL
5440: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c  ITE_IOERR | (17<
5450: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5460: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45  ITE_IOERR_SHMOPE
5470: 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  N           (SQL
5480: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c  ITE_IOERR | (18<
5490: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
54a0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a  ITE_IOERR_SHMSIZ
54b0: 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  E           (SQL
54c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c  ITE_IOERR | (19<
54d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
54e0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43  ITE_IOERR_SHMLOC
54f0: 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  K           (SQL
5500: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c  ITE_IOERR | (20<
5510: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5520: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50  ITE_IOERR_SHMMAP
5530: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5540: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c  ITE_IOERR | (21<
5550: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5560: 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20  ITE_IOERR_SEEK  
5570: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5580: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c  ITE_IOERR | (22<
5590: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
55a0: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
55b0: 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c  _NOENT      (SQL
55c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c  ITE_IOERR | (23<
55d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
55e0: 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20  ITE_IOERR_MMAP  
55f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5600: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c  ITE_IOERR | (24<
5610: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5620: 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d  ITE_IOERR_GETTEM
5630: 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  PPATH       (SQL
5640: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c  ITE_IOERR | (25<
5650: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5660: 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41  ITE_IOERR_CONVPA
5670: 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  TH          (SQL
5680: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c  ITE_IOERR | (26<
5690: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56a0: 49 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20  ITE_IOERR_VNODE 
56b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
56c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c  ITE_IOERR | (27<
56d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56e0: 49 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20 20  ITE_IOERR_AUTH  
56f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5700: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c  ITE_IOERR | (28<
5710: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5720: 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45  ITE_LOCKED_SHARE
5730: 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c  DCACHE      (SQL
5740: 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31  ITE_LOCKED |  (1
5750: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5760: 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45  LITE_BUSY_RECOVE
5770: 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51  RY           (SQ
5780: 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28  LITE_BUSY   |  (
5790: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
57a0: 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53  QLITE_BUSY_SNAPS
57b0: 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28 53  HOT           (S
57c0: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20  QLITE_BUSY   |  
57d0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
57e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
57f0: 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 28  NOTEMPDIR      (
5800: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5810: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5820: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5830: 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20 20  N_ISDIR         
5840: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5850: 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  N | (2<<8)).#def
5860: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5870: 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20  PEN_FULLPATH    
5880: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
5890: 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  PEN | (3<<8)).#d
58a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
58b0: 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20  TOPEN_CONVPATH  
58c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
58d0: 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a  TOPEN | (4<<8)).
58e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
58f0: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20  ORRUPT_VTAB     
5900: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5910: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29  ORRUPT | (1<<8))
5920: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5930: 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52  READONLY_RECOVER
5940: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  Y       (SQLITE_
5950: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38  READONLY | (1<<8
5960: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5970: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c  E_READONLY_CANTL
5980: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  OCK       (SQLIT
5990: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c  E_READONLY | (2<
59a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
59b0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c  ITE_READONLY_ROL
59c0: 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c  LBACK       (SQL
59d0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
59e0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
59f0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44  QLITE_READONLY_D
5a00: 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28 53  BMOVED        (S
5a10: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5a20: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5a30: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f   SQLITE_ABORT_RO
5a40: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20  LLBACK          
5a50: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20  (SQLITE_ABORT | 
5a60: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5a70: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a80: 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 28  T_CHECK        (
5a90: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5aa0: 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  T | (1<<8)).#def
5ab0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5ac0: 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b  RAINT_COMMITHOOK
5ad0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5ae0: 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a  RAINT | (2<<8)).
5af0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5b00: 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47  ONSTRAINT_FOREIG
5b10: 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  NKEY   (SQLITE_C
5b20: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c  ONSTRAINT | (3<<
5b30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5b40: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55  TE_CONSTRAINT_FU
5b50: 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49  NCTION     (SQLI
5b60: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5b70: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5b80: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b90: 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28  T_NOTNULL      (
5ba0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5bb0: 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  T | (5<<8)).#def
5bc0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5bd0: 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59  RAINT_PRIMARYKEY
5be0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5bf0: 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a  RAINT | (6<<8)).
5c00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5c10: 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45  ONSTRAINT_TRIGGE
5c20: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5c30: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c  ONSTRAINT | (7<<
5c40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5c50: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e  TE_CONSTRAINT_UN
5c60: 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c 49  IQUE       (SQLI
5c70: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5c80: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (8<<8)).#define 
5c90: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5ca0: 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 28  T_VTAB         (
5cb0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5cc0: 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  T | (9<<8)).#def
5cd0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5ce0: 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20  RAINT_ROWID     
5cf0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5d00: 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a  RAINT |(10<<8)).
5d10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
5d20: 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41  OTICE_RECOVER_WA
5d30: 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e  L      (SQLITE_N
5d40: 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a  OTICE | (1<<8)).
5d50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
5d60: 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f  OTICE_RECOVER_RO
5d70: 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e  LLBACK (SQLITE_N
5d80: 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a  OTICE | (2<<8)).
5d90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57  #define SQLITE_W
5da0: 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58  ARNING_AUTOINDEX
5db0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57         (SQLITE_W
5dc0: 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29  ARNING | (1<<8))
5dd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5de0: 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 20 20  AUTH_USER       
5df0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5e00: 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23  AUTH | (1<<8)).#
5e10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
5e20: 5f 4c 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c  _LOAD_PERMANENTL
5e30: 59 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b  Y     (SQLITE_OK
5e40: 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a   | (1<<8))../*.*
5e50: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
5e60: 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20  s For File Open 
5e70: 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  Operations.**.**
5e80: 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65   These bit value
5e90: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
5ea0: 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a  or use in the.**
5eb0: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
5ec0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  o the [sqlite3_o
5ed0: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
5ee0: 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68  ace and.** in th
5ef0: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
5f00: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5f10: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
5f20: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d..*/.#define SQ
5f30: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
5f40: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
5f50: 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72  00001  /* Ok for
5f60: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5f70: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5f80: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
5f90: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
5fa0: 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72  00002  /* Ok for
5fb0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5fc0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5fd0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
5fe0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5ff0: 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72  00004  /* Ok for
6000: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6010: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6020: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
6030: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
6040: 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e  00008  /* VFS on
6050: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6060: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
6070: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
6080: 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00010  /* VFS on
6090: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
60a0: 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52  LITE_OPEN_AUTOPR
60b0: 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30  OXY        0x000
60c0: 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00020  /* VFS on
60d0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
60e0: 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20  LITE_OPEN_URI   
60f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6100: 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00040  /* Ok for
6110: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6120: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6130: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59  LITE_OPEN_MEMORY
6140: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6150: 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00080  /* Ok for
6160: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6170: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6180: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
6190: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
61a0: 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00100  /* VFS on
61b0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
61c0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
61d0: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
61e0: 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00200  /* VFS on
61f0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6200: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
6210: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
6220: 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00400  /* VFS on
6230: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6240: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
6250: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
6260: 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00800  /* VFS on
6270: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6280: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
6290: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
62a0: 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  01000  /* VFS on
62b0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
62c0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
62d0: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
62e0: 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  02000  /* VFS on
62f0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6300: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
6310: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
6320: 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  04000  /* VFS on
6330: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6340: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
6350: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  X          0x000
6360: 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  08000  /* Ok for
6370: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6380: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6390: 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
63a0: 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30  TEX        0x000
63b0: 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  10000  /* Ok for
63c0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
63d0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
63e0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
63f0: 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30  CACHE      0x000
6400: 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  20000  /* Ok for
6410: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6420: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6430: 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
6440: 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30  ECACHE     0x000
6450: 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  40000  /* Ok for
6460: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6470: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6480: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20  LITE_OPEN_WAL   
6490: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
64a0: 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  80000  /* VFS on
64b0: 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76  ly */../* Reserv
64c0: 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20  ed:             
64d0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
64e0: 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  F00000 */../*.**
64f0: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63   CAPI3REF: Devic
6500: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63  e Characteristic
6510: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76  s.**.** The xDev
6520: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
6530: 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  cs method of the
6540: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6550: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  hods].** object 
6560: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
6570: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65  er which is a ve
6580: 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a  ctor of these.**
6590: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
65a0: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
65b0: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
65c0: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
65d0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
65e0: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
65f0: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
6600: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
6610: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** T
6620: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6630: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
6640: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
6650: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
6660: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
6670: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6680: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
6690: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
66a0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
66b0: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
66c0: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
66d0: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
66e0: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
66f0: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
6700: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
6710: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
6720: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6730: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
6740: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
6750: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
6760: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
6770: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
6780: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
6790: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
67a0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
67b0: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
67c0: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
67d0: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
67e0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
67f0: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
6800: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
6810: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
6820: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
6830: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
6840: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
6850: 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54  te().  The SQLIT
6860: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
6870: 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70  E_OVERWRITE prop
6880: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
6890: 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20  ** after reboot 
68a0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73  following a cras
68b0: 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c  h or power loss,
68c0: 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20   the only bytes 
68d0: 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61  in a.** file tha
68e0: 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61  t were written a
68f0: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
6900: 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61  n level might ha
6910: 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e  ve changed.** an
6920: 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20  d that adjacent 
6930: 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65  bytes, even byte
6940: 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
6950: 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20  e sector are.** 
6960: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
6970: 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
6980: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6990: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
69a0: 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69  PEN.** flag indi
69b0: 63 61 74 65 73 20 74 68 61 74 20 61 20 66 69 6c  cates that a fil
69c0: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65  e cannot be dele
69d0: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20  ted when open.  
69e0: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  The.** SQLITE_IO
69f0: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c  CAP_IMMUTABLE fl
6a00: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
6a10: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e  t the file is on
6a20: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65  .** read-only me
6a30: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62  dia and cannot b
6a40: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62  e changed even b
6a50: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68  y processes with
6a60: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69  .** elevated pri
6a70: 76 69 6c 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  vileges..**.** T
6a80: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6a90: 42 41 54 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f  BATCH_ATOMIC pro
6aa0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6ab0: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a   the underlying.
6ac0: 2a 2a 20 66 69 6c 65 73 79 73 74 65 6d 20 63 61  ** filesystem ca
6ad0: 6e 20 6d 75 6c 74 69 70 6c 65 20 77 72 69 74 65  n multiple write
6ae0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 74 6f 6d   operations atom
6af0: 69 63 61 6c 6c 79 20 77 68 65 6e 20 74 68 6f 73  ically when thos
6b00: 65 0a 2a 2a 20 77 72 69 74 65 20 6f 70 65 72 61  e.** write opera
6b10: 74 69 6f 6e 73 20 61 72 65 20 62 72 61 63 6b 65  tions are bracke
6b20: 74 65 64 20 62 79 20 5b 53 51 4c 49 54 45 5f 49  ted by [SQLITE_I
6b30: 4f 43 41 50 5f 42 45 47 49 4e 5f 41 54 4f 4d 49  OCAP_BEGIN_ATOMI
6b40: 43 5f 57 52 49 54 45 5d 20 61 6e 64 0a 2a 2a 20  C_WRITE] and.** 
6b50: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
6b60: 4f 4d 49 43 5f 57 52 49 54 45 5f 43 4f 4d 4d 49  OMIC_WRITE_COMMI
6b70: 54 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  T]..*/.#define S
6b80: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6b90: 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  IC              
6ba0: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
6bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6bc0: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20  AP_ATOMIC512    
6bd0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6be0: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
6bf0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6c00: 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  1K              
6c10: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
6c20: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6c30: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
6c40: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6c50: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
6c60: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
6c70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6c80: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
6c90: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6ca0: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20  TOMIC8K         
6cb0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
6cc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6cd0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
6ce0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6cf0: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
6d00: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6d10: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20  MIC32K          
6d20: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
6d30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6d40: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
6d50: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6d60: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
6d70: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
6d80: 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20  APPEND          
6d90: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
6da0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6db0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
6dc0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6dd0: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  400.#define SQLI
6de0: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
6df0: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20  ABLE_WHEN_OPEN  
6e00: 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69  0x00000800.#defi
6e10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6e20: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
6e30: 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30  ITE    0x0000100
6e40: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6e50: 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
6e60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6e70: 30 30 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65  00002000.#define
6e80: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41   SQLITE_IOCAP_BA
6e90: 54 43 48 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  TCH_ATOMIC      
6ea0: 20 20 20 20 20 30 78 30 30 30 30 34 30 30 30 0a       0x00004000.
6eb0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6ec0: 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65   File Locking Le
6ed0: 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  vels.**.** SQLit
6ee0: 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68  e uses one of th
6ef0: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
6f00: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
6f10: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
6f20: 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74  calls it makes t
6f30: 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e  o the xLock() an
6f40: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68  d xUnlock() meth
6f50: 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71  ods.** of an [sq
6f60: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6f70: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65  ] object..*/.#de
6f80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6f90: 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30  _NONE          0
6fa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6fb0: 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20  LOCK_SHARED     
6fc0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
6fd0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
6fe0: 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  D      2.#define
6ff0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e   SQLITE_LOCK_PEN
7000: 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65  DING       3.#de
7010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
7020: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34  _EXCLUSIVE     4
7030: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7040: 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  : Synchronizatio
7050: 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a  n Type Flags.**.
7060: 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69  ** When SQLite i
7070: 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63  nvokes the xSync
7080: 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a  () method of an.
7090: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
70a0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69  ethods] object i
70b0: 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61  t uses a combina
70c0: 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65  tion of.** these
70d0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
70e0: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
70f0: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68  gument..**.** Wh
7100: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  en the SQLITE_SY
7110: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67  NC_DATAONLY flag
7120: 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61   is used, it mea
7130: 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73  ns that the.** s
7140: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e  ync operation on
7150: 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73  ly needs to flus
7160: 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73  h data to mass s
7170: 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a  torage.  Inode.*
7180: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65  * information ne
7190: 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65  ed not be flushe
71a0: 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  d. If the lower 
71b0: 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65  four bits of the
71c0: 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53   flag.** equal S
71d0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
71e0: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f  L, that means to
71f0: 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   use normal fsyn
7200: 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a  c() semantics..*
7210: 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  * If the lower f
7220: 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53  our bits equal S
7230: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
7240: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
7250: 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73  o use Mac OS X s
7260: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e  tyle fullsync in
7270: 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29  stead of fsync()
7280: 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63  ..**.** Do not c
7290: 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54  onfuse the SQLIT
72a0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
72b0: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
72c0: 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68  LL flags.** with
72d0: 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e   the [PRAGMA syn
72e0: 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c  chronous]=NORMAL
72f0: 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e   and [PRAGMA syn
7300: 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a  chronous]=FULL.*
7310: 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65  * settings.  The
7320: 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72   [synchronous pr
7330: 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73  agma] determines
7340: 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74   when calls to t
7350: 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20  he.** xSync VFS 
7360: 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64  method occur and
7370: 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d   applies uniform
7380: 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c  ly across all pl
7390: 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20  atforms..** The 
73a0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
73b0: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
73c0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65  NC_FULL flags de
73d0: 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65  termine how.** e
73e0: 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f  nergetic or rigo
73f0: 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c  rous or forceful
7400: 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74   the sync operat
7410: 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20  ions are and.** 
7420: 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66  only make a diff
7430: 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53  erence on Mac OS
7440: 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c  X for the defaul
7450: 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a  t SQLite code..*
7460: 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56  * (Third-party V
7470: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7480: 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61  ns might also ma
7490: 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
74a0: 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51  on.** between SQ
74b0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
74c0: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
74d0: 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67  _FULL, but among
74e0: 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e   the.** operatin
74f0: 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65  g systems native
7500: 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  ly supported by 
7510: 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63  SQLite, only Mac
7520: 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62   OSX.** cares ab
7530: 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e  out the differen
7540: 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ce.).*/.#define 
7550: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7560: 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30  AL        0x0000
7570: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
7580: 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20  _SYNC_FULL      
7590: 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66      0x00003.#def
75a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
75b0: 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78  DATAONLY      0x
75c0: 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00010../*.** CAP
75d0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
75e0: 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61  ace Open File Ha
75f0: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73  ndle.**.** An [s
7600: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7610: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
7620: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74  n open file in t
7630: 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
7640: 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61  vfs | OS interfa
7650: 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69  ce layer].  Indi
7660: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
7670: 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ace.** implement
7680: 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77  ations will.** w
7690: 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20  ant to subclass 
76a0: 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61  this object by a
76b0: 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f  ppending additio
76c0: 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f  nal fields.** fo
76d0: 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e  r their own use.
76e0: 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65    The pMethods e
76f0: 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65  ntry is a pointe
7700: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
7710: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
7720: 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
7730: 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20  nes methods for 
7740: 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f  performing.** I/
7750: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20  O operations on 
7760: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
7770: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
7780: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71   sqlite3_file sq
7790: 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75  lite3_file;.stru
77a0: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
77b0: 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74  {.  const struct
77c0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
77d0: 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20  ods *pMethods;  
77e0: 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61  /* Methods for a
77f0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d  n open file */.}
7800: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7810: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
7820: 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74  File Virtual Met
7830: 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  hods Object.**.*
7840: 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65  * Every file ope
7850: 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ned by the [sqli
7860: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
7870: 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20  ethod populates 
7880: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  an.** [sqlite3_f
7890: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c  ile] object (or,
78a0: 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20   more commonly, 
78b0: 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68  a subclass of th
78c0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
78d0: 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68  le] object) with
78e0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
78f0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
7900: 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69  s object..** Thi
7910: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
7920: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65   the methods use
7930: 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  d to perform var
7940: 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a  ious operations.
7950: 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f  ** against the o
7960: 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65  pen file represe
7970: 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  nted by the [sql
7980: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7990: 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
79a0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
79b0: 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20  en] method sets 
79c0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
79d0: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
79e0: 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e  t .** to a non-N
79f0: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
7a00: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f  n the sqlite3_io
7a10: 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20  _methods.xClose 
7a20: 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65  method.** may be
7a30: 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66   invoked even if
7a40: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7a50: 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65  s.xOpen] reporte
7a60: 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64  d that it failed
7a70: 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77  .  The.** only w
7a80: 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ay to prevent a 
7a90: 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66  call to xClose f
7aa0: 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65  ollowing a faile
7ab0: 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  d [sqlite3_vfs.x
7ac0: 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20  Open].** is for 
7ad0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7ae0: 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74  .xOpen] to set t
7af0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
7b00: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
7b10: 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a  .** to NULL..**.
7b20: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
7b30: 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d  ument to xSync m
7b40: 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51  ay be one of [SQ
7b50: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7b60: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
7b70: 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65  SYNC_FULL].  The
7b80: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73   first choice is
7b90: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   the normal fsyn
7ba0: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  c()..** The seco
7bb0: 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d  nd choice is a M
7bc0: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
7bd0: 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51  llsync.  The [SQ
7be0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
7bf0: 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20  LY].** flag may 
7c00: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e  be ORed in to in
7c10: 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79  dicate that only
7c20: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65   the data of the
7c30: 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74   file.** and not
7c40: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73   its inode needs
7c50: 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a   to be synced..*
7c60: 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72  *.** The integer
7c70: 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b   values to xLock
7c80: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
7c90: 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c   are one of.** <
7ca0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
7cb0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a  ITE_LOCK_NONE],.
7cc0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7cd0: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
7ce0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7cf0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a  CK_RESERVED],.**
7d00: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7d10: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a  CK_PENDING], or.
7d20: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7d30: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e  LOCK_EXCLUSIVE].
7d40: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f  .** </ul>.** xLo
7d50: 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74  ck() increases t
7d60: 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b  he lock. xUnlock
7d70: 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65  () decreases the
7d80: 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43   lock..** The xC
7d90: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
7da0: 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73  () method checks
7db0: 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74   whether any dat
7dc0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
7dd0: 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74  ,.** either in t
7de0: 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69  his process or i
7df0: 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f  n some other pro
7e00: 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67  cess, is holding
7e10: 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20   a RESERVED,.** 
7e20: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c  PENDING, or EXCL
7e30: 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68  USIVE lock on th
7e40: 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75  e file.  It retu
7e50: 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73  rns true.** if s
7e60: 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74  uch a lock exist
7e70: 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65  s and false othe
7e80: 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rwise..**.** The
7e90: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
7ea0: 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65  method is a gene
7eb0: 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68  ric interface th
7ec0: 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d  at allows custom
7ed0: 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  .** VFS implemen
7ee0: 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63  tations to direc
7ef0: 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f  tly control an o
7f00: 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74  pen file using t
7f10: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
7f20: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
7f30: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73  nterface.  The s
7f40: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d  econd "op" argum
7f50: 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74  ent is an.** int
7f60: 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68  eger opcode.  Th
7f70: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
7f80: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f   is a generic po
7f90: 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74  inter intended t
7fa0: 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20  o.** point to a 
7fb0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d  structure that m
7fc0: 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d  ay contain argum
7fd0: 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e  ents or space in
7fe0: 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69   which to.** wri
7ff0: 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  te return values
8000: 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65  .  Potential use
8010: 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72  s for xFileContr
8020: 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a  ol() might be.**
8030: 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e   functions to en
8040: 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f  able blocking lo
8050: 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74  cks with timeout
8060: 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  s, to change the
8070: 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61  .** locking stra
8080: 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c  tegy (for exampl
8090: 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c  e to use dot-fil
80a0: 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71  e locks), to inq
80b0: 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68  uire.** about th
80c0: 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f  e status of a lo
80d0: 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20  ck, or to break 
80e0: 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68  stale locks.  Th
80f0: 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65  e SQLite.** core
8100: 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70   reserves all op
8110: 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20  codes less than 
8120: 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20  100 for its own 
8130: 75 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20  use..** A [file 
8140: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20  control opcodes 
8150: 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65  | list of opcode
8160: 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  s] less than 100
8170: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
8180: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
8190: 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73  hat define a cus
81a0: 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  tom xFileControl
81b0: 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75   method should u
81c0: 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72  se opcodes.** gr
81d0: 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74  eater than 100 t
81e0: 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74  o avoid conflict
81f0: 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  s.  VFS implemen
8200: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a  tations should.*
8210: 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
8220: 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66  _NOTFOUND] for f
8230: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
8240: 64 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f  des that they do
8250: 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a   not.** recogniz
8260: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65  e..**.** The xSe
8270: 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f  ctorSize() metho
8280: 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65  d returns the se
8290: 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65  ctor size of the
82a0: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
82b0: 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69  underlies the fi
82c0: 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20  le.  The sector 
82d0: 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d  size is the.** m
82e0: 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61  inimum write tha
82f0: 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d  t can be perform
8300: 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75  ed without distu
8310: 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62  rbing.** other b
8320: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
8330: 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68  .  The xDeviceCh
8340: 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a  aracteristics().
8350: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
8360: 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64  s a bit vector d
8370: 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69  escribing behavi
8380: 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e  ors of the.** un
8390: 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a  derlying device:
83a0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
83b0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
83c0: 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69  P_ATOMIC].** <li
83d0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
83e0: 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c  ATOMIC512].** <l
83f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8400: 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC1K].** <l
8410: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8420: 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC2K].** <l
8430: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8440: 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC4K].** <l
8450: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8460: 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC8K].** <l
8470: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8480: 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c  _ATOMIC16K].** <
8490: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
84a0: 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20  P_ATOMIC32K].** 
84b0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
84c0: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a  AP_ATOMIC64K].**
84d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
84e0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d  CAP_SAFE_APPEND]
84f0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8500: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
8510: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  L].** <li> [SQLI
8520: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
8530: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 5d 0a  ABLE_WHEN_OPEN].
8540: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8550: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
8560: 4f 56 45 52 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c  OVERWRITE].** <l
8570: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8580: 5f 49 4d 4d 55 54 41 42 4c 45 5d 0a 2a 2a 20 3c  _IMMUTABLE].** <
8590: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
85a0: 50 5f 42 41 54 43 48 5f 41 54 4f 4d 49 43 5d 0a  P_BATCH_ATOMIC].
85b0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
85c0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
85d0: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
85e0: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
85f0: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
8600: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
8610: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8620: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
8630: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
8640: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
8650: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
8660: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
8670: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
8680: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
8690: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
86a0: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
86b0: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
86c0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
86d0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
86e0: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
86f0: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
8700: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
8710: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
8720: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
8730: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
8740: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
8750: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
8760: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
8770: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
8780: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
8790: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
87a0: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
87b0: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
87c0: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
87d0: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
87e0: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
87f0: 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78  te()..**.** If x
8800: 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53  Read() returns S
8810: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
8820: 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61  T_READ it must a
8830: 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74  lso fill.** in t
8840: 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f  he unread portio
8850: 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ns of the buffer
8860: 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20   with zeros.  A 
8870: 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c  VFS that.** fail
8880: 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  s to zero-fill s
8890: 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74  hort reads might
88a0: 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20   seem to work.  
88b0: 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c  However,.** fail
88c0: 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ure to zero-fill
88d0: 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c   short reads wil
88e0: 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61  l eventually lea
88f0: 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65  d to.** database
8900: 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
8910: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
8920: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8930: 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  s sqlite3_io_met
8940: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
8950: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
8960: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
8970: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
8980: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8990: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29  ;.  int (*xRead)
89a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
89b0: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
89c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
89d0: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
89e0: 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66  Write)(sqlite3_f
89f0: 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ile*, const void
8a00: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
8a10: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
8a20: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e  );.  int (*xTrun
8a30: 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  cate)(sqlite3_fi
8a40: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
8a50: 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20  64 size);.  int 
8a60: 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
8a70: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67  _file*, int flag
8a80: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  s);.  int (*xFil
8a90: 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  eSize)(sqlite3_f
8aa0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8ab0: 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69  t64 *pSize);.  i
8ac0: 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69  nt (*xLock)(sqli
8ad0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
8ae0: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b  .  int (*xUnlock
8af0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8b00: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
8b10: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
8b20: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8b30: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
8b40: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f  .  int (*xFileCo
8b50: 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66  ntrol)(sqlite3_f
8b60: 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f  ile*, int op, vo
8b70: 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74  id *pArg);.  int
8b80: 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28   (*xSectorSize)(
8b90: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8ba0: 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43    int (*xDeviceC
8bb0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28  haracteristics)(
8bc0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8bd0: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
8be0: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
8bf0: 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20   version 1 */.  
8c00: 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73  int (*xShmMap)(s
8c10: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8c20: 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c  t iPg, int pgsz,
8c30: 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74   int, void volat
8c40: 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  ile**);.  int (*
8c50: 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65  xShmLock)(sqlite
8c60: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66  3_file*, int off
8c70: 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20  set, int n, int 
8c80: 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28  flags);.  void (
8c90: 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71  *xShmBarrier)(sq
8ca0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8cb0: 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29  int (*xShmUnmap)
8cc0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8cd0: 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b  int deleteFlag);
8ce0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8cf0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8d00: 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20  r version 2 */. 
8d10: 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73   int (*xFetch)(s
8d20: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8d30: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8d40: 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69  t, int iAmt, voi
8d50: 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28  d **pp);.  int (
8d60: 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74  *xUnfetch)(sqlit
8d70: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8d80: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76  3_int64 iOfst, v
8d90: 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65  oid *p);.  /* Me
8da0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8db0: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8dc0: 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69  n 3 */.  /* Addi
8dd0: 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d  tional methods m
8de0: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
8df0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a  uture releases *
8e00: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
8e10: 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46  3REF: Standard F
8e20: 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f  ile Control Opco
8e30: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
8e40: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
8e50: 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f  pcodes} {file co
8e60: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a  ntrol opcode}.**
8e70: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
8e80: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
8e90: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
8ea0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
8eb0: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
8ec0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8ed0: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
8ee0: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
8ef0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
8f00: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
8f10: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b  ** <ul>.** <li>[
8f20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
8f30: 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 65  CKSTATE]].** The
8f40: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
8f50: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
8f60: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
8f70: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
8f80: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
8f90: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
8fa0: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
8fb0: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
8fc0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
8fd0: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
8fe0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
8ff0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
9000: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
9010: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
9020: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
9030: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
9040: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
9050: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
9060: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
9070: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
9080: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
9090: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
90a0: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
90b0: 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  and is only avai
90c0: 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20 53  lable when the S
90d0: 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63 6f  QLITE_TEST.** co
90e0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
90f0: 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
9100: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9110: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a  NTL_SIZE_HINT]].
9120: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9130: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20  CNTL_SIZE_HINT] 
9140: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62  opcode is used b
9150: 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65  y SQLite to give
9160: 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65   the VFS.** laye
9170: 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20  r a hint of how 
9180: 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61  large the databa
9190: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f  se file will gro
91a0: 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74  w to be during t
91b0: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72  he.** current tr
91c0: 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73  ansaction.  This
91d0: 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61   hint is not gua
91e0: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63  ranteed to be ac
91f0: 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a  curate but it.**
9200: 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e   is often close.
9210: 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67    The underlying
9220: 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73   VFS might choos
9230: 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65  e to preallocate
9240: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
9250: 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e  e space based on
9260: 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72   this hint in or
9270: 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74  der to help writ
9280: 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  es to the databa
9290: 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66  se.** file run f
92a0: 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  aster..**.** <li
92b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
92c0: 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  CHUNK_SIZE]].** 
92d0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
92e0: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70  L_CHUNK_SIZE] op
92f0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9300: 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65  request that the
9310: 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20   VFS.** extends 
9320: 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68  and truncates th
9330: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9340: 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73  in chunks of a s
9350: 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ize specified.**
9360: 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68   by the user. Th
9370: 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
9380: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69  t to [sqlite3_fi
9390: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68  le_control()] sh
93a0: 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74  ould .** point t
93b0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79  o an integer (ty
93c0: 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69  pe int) containi
93d0: 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b  ng the new chunk
93e0: 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20  -size to use.** 
93f0: 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65  for the nominate
9400: 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f  d database. Allo
9410: 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  cating database 
9420: 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61  file space in la
9430: 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73  rge.** chunks (s
9440: 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65  ay 1MB at a time
9450: 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69  ), may reduce fi
9460: 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65  le-system fragme
9470: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69  ntation and.** i
9480: 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
9490: 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65  ce on some syste
94a0: 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ms..**.** <li>[[
94b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
94c0: 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54  E_POINTER]].** T
94d0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
94e0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f  _FILE_POINTER] o
94f0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9500: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65   obtain a pointe
9510: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  r.** to the [sql
9520: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
9530: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
9540: 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64  h a particular d
9550: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
9560: 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f  ction.  See also
9570: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a   [SQLITE_FCNTL_J
9580: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e  OURNAL_POINTER].
9590: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
95a0: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
95b0: 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54  L_POINTER]].** T
95c0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
95d0: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
95e0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
95f0: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69   to obtain a poi
9600: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
9610: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
9620: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20  ject associated 
9630: 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c  with the journal
9640: 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a   file (either.**
9650: 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a   the [rollback j
9660: 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b  ournal] or the [
9670: 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d  write-ahead log]
9680: 29 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ) for a particul
9690: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
96a0: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
96b0: 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e  also [SQLITE_FCN
96c0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
96d0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
96e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
96f0: 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20  OMITTED]].** No 
9700: 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a  longer in use..*
9710: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9720: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a  E_FCNTL_SYNC]].*
9730: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9740: 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65  NTL_SYNC] opcode
9750: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
9760: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69  ternally by SQLi
9770: 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74  te and.** sent t
9780: 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69  o the VFS immedi
9790: 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65  ately before the
97a0: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73   xSync method is
97b0: 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a   invoked on a.**
97c0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64   database file d
97d0: 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69  escriptor. Or, i
97e0: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
97f0: 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  od is not invoke
9800: 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68  d .** because th
9810: 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69  e user has confi
9820: 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74  gured SQLite wit
9830: 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79  h .** [PRAGMA sy
9840: 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47  nchronous | PRAG
9850: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f  MA synchronous=O
9860: 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  FF] it is invoke
9870: 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f  d in place .** o
9880: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
9890: 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65  od. In most case
98a0: 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61  s, the pointer a
98b0: 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77  rgument passed w
98c0: 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65  ith.** this file
98d0: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c  -control is NULL
98e0: 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68  . However, if th
98f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9900: 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a  is being synced.
9910: 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20  ** as part of a 
9920: 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63  multi-database c
9930: 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d  ommit, the argum
9940: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  ent points to a 
9950: 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
9960: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
9970: 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74  ing the transact
9980: 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72  ions master-jour
9990: 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56  nal file name. V
99a0: 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f  FSes that .** do
99b0: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
99c0: 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c  ignal should sil
99d0: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
99e0: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
99f0: 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c  ations .** shoul
9a00: 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69  d not call [sqli
9a10: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9a20: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70  ()] with this op
9a30: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
9a40: 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74   may .** disrupt
9a50: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f   the operation o
9a60: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
9a70: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  d VFSes that do 
9a80: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
9a90: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9aa0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
9ab0: 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20  ASETWO]].** The 
9ac0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
9ad0: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f  MMIT_PHASETWO] o
9ae0: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
9af0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
9b00: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73   SQLite.** and s
9b10: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61  ent to the VFS a
9b20: 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  fter a transacti
9b30: 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d  on has been comm
9b40: 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  itted immediatel
9b50: 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20  y.** but before 
9b60: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
9b70: 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20  unlocked. VFSes 
9b80: 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64  that do not need
9b90: 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20   this signal.** 
9ba0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
9bb0: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
9bc0: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
9bd0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
9be0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
9bf0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
9c00: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73  h this opcode as
9c10: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69   doing so may di
9c20: 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70  srupt the .** op
9c30: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  eration of the s
9c40: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
9c50: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
9c60: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
9c70: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9c80: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d  WIN32_AV_RETRY]]
9c90: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
9ca0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
9cb0: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73  RETRY] opcode is
9cc0: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
9cd0: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20  re automatic.** 
9ce0: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64  retry counts and
9cf0: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63   intervals for c
9d00: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20  ertain disk I/O 
9d10: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74  operations for t
9d20: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56  he.** windows [V
9d30: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  FS] in order to 
9d40: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65  provide robustne
9d50: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e  ss in the presen
9d60: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69  ce of.** anti-vi
9d70: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42  rus programs.  B
9d80: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77  y default, the w
9d90: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20  indows VFS will 
9da0: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c  retry file read,
9db0: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20  .** file write, 
9dc0: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20  and file delete 
9dd0: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f  operations up to
9de0: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20   10 times, with 
9df0: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35  a delay.** of 25
9e00: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65   milliseconds be
9e10: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72  fore the first r
9e20: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68  etry and with th
9e30: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69  e delay increasi
9e40: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69  ng.** by an addi
9e50: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73  tional 25 millis
9e60: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68  econds with each
9e70: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72   subsequent retr
9e80: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  y.  This.** opco
9e90: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20  de allows these 
9ea0: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72  two values (10 r
9eb0: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69  etries and 25 mi
9ec0: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65  lliseconds of de
9ed0: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64  lay).** to be ad
9ee0: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c  justed.  The val
9ef0: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20  ues are changed 
9f00: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65  for all database
9f10: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
9f20: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
9f30: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72  process.  The ar
9f40: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
9f50: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20  ter to an array 
9f60: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65  of two.** intege
9f70: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72  rs where the fir
9f80: 73 74 20 69 6e 74 65 67 65 72 20 69 73 20 74 68  st integer is th
9f90: 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e  e new retry coun
9fa0: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
9fb0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74  .** integer is t
9fc0: 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69  he delay.  If ei
9fd0: 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20  ther integer is 
9fe0: 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
9ff0: 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73  he setting.** is
a000: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74   not changed but
a010: 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69   instead the pri
a020: 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  or value of that
a030: 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74   setting is writ
a040: 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ten.** into the 
a050: 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c  array entry, all
a060: 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e  owing the curren
a070: 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73  t retry settings
a080: 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72   to be.** interr
a090: 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62  ogated.  The zDb
a0a0: 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  Name parameter i
a0b0: 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
a0c0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a0d0: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
a0e0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a0f0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
a100: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  WAL] opcode is u
a110: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
a120: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
a130: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69  stent [WAL | Wri
a140: 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65  te Ahead Log] se
a150: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75  tting.  By defau
a160: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72  lt, the auxiliar
a170: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64  y.** write ahead
a180: 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20   log and shared 
a190: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65  memory files use
a1a0: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f  d for transactio
a1b0: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65  n control.** are
a1c0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
a1d0: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20  eleted when the 
a1e0: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f  latest connectio
a1f0: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  n to the databas
a200: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65  e.** closes.  Se
a210: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74  tting persistent
a220: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73   WAL mode causes
a230: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20   those files to 
a240: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a  persist after.**
a250: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74   close.  Persist
a260: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73  ing the files is
a270: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68   useful when oth
a280: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61  er processes tha
a290: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65  t do not.** have
a2a0: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f   write permissio
a2b0: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f  n on the directo
a2c0: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ry containing th
a2d0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a2e0: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20  want.** to read 
a2f0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
a300: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e  e, as the WAL an
a310: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
a320: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74  files must exist
a330: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72  .** in order for
a340: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f   the database to
a350: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54   be readable.  T
a360: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
a370: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
a380: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
a390: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
a3a0: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
a3b0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
a3c0: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
a3d0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
a3e0: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  sable persistent
a3f0: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74   WAL mode or 1 t
a400: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74  o enable persist
a410: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e  ent.** WAL mode.
a420: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
a430: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
a440: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
a450: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
a460: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e  ** WAL persisten
a470: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  ce setting..**.*
a480: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a490: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a4a0: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
a4b0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a4c0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
a4d0: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
a4e0: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
a4f0: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
a500: 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66  istent "powersaf
a510: 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20  e-overwrite" or 
a520: 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20  "PSOW" setting. 
a530: 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e   The PSOW settin
a540: 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20  g.** determines 
a550: 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  the [SQLITE_IOCA
a560: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
a570: 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68  WRITE] bit of th
a580: 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72  e.** xDeviceChar
a590: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
a5a0: 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ods. The fourth 
a5b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
a5c0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a5d0: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
a5e0: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
a5f0: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
a600: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
a610: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
a620: 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f   to disable zero
a630: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20  -damage mode or 
a640: 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f  1 to enable zero
a650: 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e  -damage.** mode.
a660: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
a670: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
a680: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
a690: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
a6a0: 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  ** zero-damage m
a6b0: 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  ode setting..**.
a6c0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a6d0: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
a6e0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a6f0: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
a700: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76  E] opcode is inv
a710: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  oked by SQLite a
a720: 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20  fter opening.** 
a730: 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74  a write transact
a740: 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ion to indicate 
a750: 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20  that, unless it 
a760: 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66  is rolled back f
a770: 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f  or some.** reaso
a780: 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61  n, the entire da
a790: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
a7a0: 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
a7b0: 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a  by the current .
a7c0: 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  ** transaction. 
a7d0: 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20  This is used by 
a7e0: 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e  VACUUM operation
a7f0: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
a800: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
a810: 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  AME]].** ^The [S
a820: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
a830: 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20  AME] opcode can 
a840: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
a850: 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a  n the names of.*
a860: 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e  * all [VFSes] in
a870: 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20   the VFS stack. 
a880: 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f   The names are o
a890: 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20  f all VFS shims 
a8a0: 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c  and the.** final
a8b0: 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46   bottom-level VF
a8c0: 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e  S are written in
a8d0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
a8e0: 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
a8f0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
a900: 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  nd the result is
a910: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63   stored in the c
a920: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a  har* variable.**
a930: 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68   that the fourth
a940: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73   parameter of [s
a950: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
a960: 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f  rol()] points to
a970: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20  ..** The caller 
a980: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
a990: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d  or freeing the m
a9a0: 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e  emory when done.
a9b0: 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c    As with.** all
a9c0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63   file-control ac
a9d0: 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20  tions, there is 
a9e0: 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  no guarantee tha
a9f0: 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75  t this will actu
aa00: 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68  ally.** do anyth
aa10: 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68  ing.  Callers sh
aa20: 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20  ould initialize 
aa30: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
aa40: 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20  le to a NULL.** 
aa50: 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20  pointer in case 
aa60: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
aa70: 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  l is not impleme
aa80: 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65  nted.  This file
aa90: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69  -control.** is i
aaa0: 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67  ntended for diag
aab0: 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e  nostic use only.
aac0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
aad0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
aae0: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  INTER]].** ^The 
aaf0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
ab00: 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  S_POINTER] opcod
ab10: 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65  e finds a pointe
ab20: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76  r to the top-lev
ab30: 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75  el.** [VFSes] cu
ab40: 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20  rrently in use. 
ab50: 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20   ^(The argument 
ab60: 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  X in.** sqlite3_
ab70: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c  file_control(db,
ab80: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
ab90: 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74  _POINTER,X) must
aba0: 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22   be.** of type "
abb0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a  [sqlite3_vfs] **
abc0: 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73  ".  This opcodes
abd0: 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20   will set *X.** 
abe0: 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  to a pointer to 
abf0: 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46  the top-level VF
ac00: 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  S.)^.** ^When th
ac10: 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65  ere are multiple
ac20: 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68   VFS shims in th
ac30: 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70  e stack, this op
ac40: 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a  code finds the.*
ac50: 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69  * upper-most shi
ac60: 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  m only..**.** <l
ac70: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ac80: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68  _PRAGMA]].** ^Wh
ac90: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41  enever a [PRAGMA
aca0: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70  ] statement is p
acb0: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54  arsed, an [SQLIT
acc0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
acd0: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
ace0: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20   is sent to the 
acf0: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  open [sqlite3_fi
ad00: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65  le] object corre
ad10: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74  sponding.** to t
ad20: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
ad30: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72   to which the pr
ad40: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72  agma statement r
ad50: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75  efers. ^The argu
ad60: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
ad70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
ad80: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
ad90: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  l is an array of
ada0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
adb0: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29  strings (char**)
adc0: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65   in which the se
add0: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20  cond element of 
ade0: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20  the array.** is 
adf0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
ae00: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74  pragma and the t
ae10: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20  hird element is 
ae20: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
ae30: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72  the.** pragma or
ae40: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61   NULL if the pra
ae50: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d  gma has no argum
ae60: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ent.  ^The handl
ae70: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  er for an.** [SQ
ae80: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
ae90: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
aea0: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d  can optionally m
aeb0: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c  ake the first el
aec0: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20  ement.** of the 
aed0: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20  char** argument 
aee0: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
aef0: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
af00: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
af10: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71  ()].** or the eq
af20: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61  uivalent and tha
af30: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  t string will be
af40: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20  come the result 
af50: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72  of the pragma or
af60: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
af70: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61  ssage if the pra
af80: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74  gma fails. ^If t
af90: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
afa0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
afb0: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
afc0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
afd0: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20  D], then normal 
afe0: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f  .** [PRAGMA] pro
aff0: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65  cessing continue
b000: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  s.  ^If the [SQL
b010: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b020: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
b030: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
b040: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20  E_OK], then the 
b050: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74  parser assumes t
b060: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68  hat the.** VFS h
b070: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50  as handled the P
b080: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64  RAGMA itself and
b090: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65   the parser gene
b0a0: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a  rates a no-op.**
b0b0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
b0c0: 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73 74  ent if result st
b0d0: 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72  ring is NULL, or
b0e0: 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 61 20   that returns a 
b0f0: 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72  copy.** of the r
b100: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20  esult string if 
b110: 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  the string is no
b120: 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74  n-NULL..** ^If t
b130: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b140: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
b150: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a  ntrol returns.**
b160: 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65   any result code
b170: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
b180: 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49  ITE_OK] or [SQLI
b190: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
b1a0: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  at means.** that
b1b0: 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74   the VFS encount
b1c0: 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68  ered an error wh
b1d0: 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65  ile handling the
b1e0: 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68   [PRAGMA] and th
b1f0: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  e.** compilation
b200: 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66   of the PRAGMA f
b210: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72  ails with an err
b220: 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  or.  ^The [SQLIT
b230: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
b240: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
b250: 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65  occurs at the be
b260: 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d  ginning of pragm
b270: 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c  a statement anal
b280: 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69  ysis and so.** i
b290: 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65  t is able to ove
b2a0: 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b  rride built-in [
b2b0: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
b2c0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ts..**.** <li>[[
b2d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
b2e0: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
b2f0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b300: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a  _BUSYHANDLER].**
b310: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61   file-control ma
b320: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20  y be invoked by 
b330: 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61  SQLite on the da
b340: 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64  tabase file hand
b350: 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66  le.** shortly af
b360: 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64  ter it is opened
b370: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
b380: 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46  vide a custom VF
b390: 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a  S with access.**
b3a0: 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   to the connecti
b3b0: 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  ons busy-handler
b3c0: 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61   callback. The a
b3d0: 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79  rgument is of ty
b3e0: 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20  pe (void **).** 
b3f0: 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  - an array of tw
b400: 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65  o (void *) value
b410: 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f  s. The first (vo
b420: 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70  id *) actually p
b430: 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75  oints.** to a fu
b440: 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28  nction of type (
b450: 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29  int (*)(void *))
b460: 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  . In order to in
b470: 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74  voke the connect
b480: 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e  ions.** busy-han
b490: 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74  dler, this funct
b4a0: 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e  ion should be in
b4b0: 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73  voked with the s
b4c0: 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69  econd (void *) i
b4d0: 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61  n.** the array a
b4e0: 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d  s the only argum
b4f0: 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72  ent. If it retur
b500: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
b510: 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  n the operation.
b520: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
b530: 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75  ried. If it retu
b540: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75  rns zero, the cu
b550: 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20  stom VFS should 
b560: 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63  abandon the.** c
b570: 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
b580: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b590: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b5a0: 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70  ILENAME]].** ^Ap
b5b0: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e  plication can in
b5c0: 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45  voke the [SQLITE
b5d0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
b5e0: 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  AME] file-contro
b5f0: 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c  l.** to have SQL
b600: 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a  ite generate a.*
b610: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
b620: 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73  name using the s
b630: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68  ame algorithm th
b640: 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74  at is followed t
b650: 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65  o generate.** te
b660: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
b670: 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65  s for TEMP table
b680: 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65  s and other inte
b690: 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a  rnal uses.  The.
b6a0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
b6b0: 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77  ld be a char** w
b6c0: 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c  hich will be fil
b6d0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c  led with the fil
b6e0: 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e  ename.** written
b6f0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
b700: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
b710: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
b720: 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c  The caller shoul
b730: 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  d.** invoke [sql
b740: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20  ite3_free()] on 
b750: 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76  the result to av
b760: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
b770: 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  k..**.** <li>[[S
b780: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
b790: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
b7a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
b7b0: 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
b7c0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20  trol is used to 
b7d0: 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65  query or set the
b7e0: 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  .** maximum numb
b7f0: 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74  er of bytes that
b800: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f   will be used fo
b810: 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20  r memory-mapped 
b820: 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  I/O..** The argu
b830: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
b840: 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20  r to a value of 
b850: 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  type sqlite3_int
b860: 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e  64 that.** is an
b870: 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75   advisory maximu
b880: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
b890: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f  s in the file to
b8a0: 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68   memory map.  Th
b8b0: 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20  e.** pointer is 
b8c0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
b8d0: 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20   the old value. 
b8e0: 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f   The limit is no
b8f0: 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20  t changed if.** 
b900: 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e  the value origin
b910: 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  ally pointed to 
b920: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64  is negative, and
b930: 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   so the current 
b940: 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65  limit .** can be
b950: 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73   queried by pass
b960: 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72  ing in a pointer
b970: 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e   to a negative n
b980: 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20  umber.  This.** 
b990: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
b9a0: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
b9b0: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52  to implement [PR
b9c0: 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e  AGMA mmap_size].
b9d0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b9e0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
b9f0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
ba00: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69  _FCNTL_TRACE] fi
ba10: 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69  le control provi
ba20: 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66  des advisory inf
ba30: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74  ormation.** to t
ba40: 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61  he VFS about wha
ba50: 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79  t the higher lay
ba60: 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ers of the SQLit
ba70: 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e  e stack are doin
ba80: 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20  g..** This file 
ba90: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
baa0: 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69  by some VFS acti
bab0: 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68  vity tracing [sh
bac0: 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ims]..** The arg
bad0: 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d  ument is a zero-
bae0: 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
baf0: 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72  g.  Higher layer
bb00: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  s in the.** SQLi
bb10: 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e  te stack may gen
bb20: 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20  erate instances 
bb30: 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  of this file con
bb40: 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b  trol if.** the [
bb50: 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c  SQLITE_USE_FCNTL
bb60: 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d  _TRACE] compile-
bb70: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
bb80: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  nabled..**.** <l
bb90: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bba0: 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20  _HAS_MOVED]].** 
bbb0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
bbc0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c  L_HAS_MOVED] fil
bbd0: 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70  e control interp
bbe0: 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e  rets its argumen
bbf0: 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  t as a.** pointe
bc00: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
bc10: 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20  and it writes a 
bc20: 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61  boolean into tha
bc30: 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64  t integer depend
bc40: 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  ing.** on whethe
bc50: 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c  r or not the fil
bc60: 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d  e has been renam
bc70: 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65  ed, moved, or de
bc80: 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a  leted since it.*
bc90: 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e  * was first open
bca0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
bcb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
bcc0: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_GET_HANDLE]].
bcd0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
bce0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
bcf0: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61  ANDLE] opcode ca
bd00: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
bd10: 61 69 6e 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72  ain the.** under
bd20: 6c 79 69 6e 67 20 6e 61 74 69 76 65 20 66 69 6c  lying native fil
bd30: 65 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 69 61  e handle associa
bd40: 74 65 64 20 77 69 74 68 20 61 20 66 69 6c 65 20  ted with a file 
bd50: 68 61 6e 64 6c 65 2e 20 20 54 68 69 73 20 66 69  handle.  This fi
bd60: 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e  le.** control in
bd70: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
bd80: 75 6d 65 6e 74 20 61 73 20 61 20 70 6f 69 6e 74  ument as a point
bd90: 65 72 20 74 6f 20 61 20 6e 61 74 69 76 65 20 66  er to a native f
bda0: 69 6c 65 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a  ile handle and.*
bdb0: 2a 20 77 72 69 74 65 73 20 74 68 65 20 72 65 73  * writes the res
bdc0: 75 6c 74 69 6e 67 20 76 61 6c 75 65 20 74 68 65  ulting value the
bdd0: 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  re..**.** <li>[[
bde0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
bdf0: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_SET_HANDLE]].
be00: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
be10: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
be20: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73  ANDLE] opcode is
be30: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
be40: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
be50: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
be60: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
be70: 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 20  hod to swap the 
be80: 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68  file handle with
be90: 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e   the one.** poin
bea0: 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 41  ted to by the pA
beb0: 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  rg argument.  Th
bec0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 73  is capability is
bed0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
bee0: 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ting.** and only
bef0: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
bf00: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
bf10: 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e  TE_TEST is defin
bf20: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
bf30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
bf40: 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20  _BLOCK]].** The 
bf50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41  [SQLITE_FCNTL_WA
bf60: 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69  L_BLOCK] is a si
bf70: 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20  gnal to the VFS 
bf80: 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 6d 69  layer that it mi
bf90: 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74  ght.** be advant
bfa0: 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20  ageous to block 
bfb0: 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20  on the next WAL 
bfc0: 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b  lock if the lock
bfd0: 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74   is not immediat
bfe0: 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65  ely.** available
bff0: 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 73 79  .  The WAL subsy
c000: 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 69 73  stem issues this
c010: 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72   signal during r
c020: 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61  are.** circumsta
c030: 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f  nces in order to
c040: 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77   fix a problem w
c050: 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76  ith priority inv
c060: 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69  ersion..** Appli
c070: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c  cations should <
c080: 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20  em>not</em> use 
c090: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
c0a0: 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  l..**.** <li>[[S
c0b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56  QLITE_FCNTL_ZIPV
c0c0: 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  FS]].** The [SQL
c0d0: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
c0e0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c  ] opcode is impl
c0f0: 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66  emented by zipvf
c100: 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65  s only. All othe
c110: 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20  r.** VFS should 
c120: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
c130: 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20  TFOUND for this 
c140: 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opcode..**.** <l
c150: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c160: 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  _RBU]].** The [S
c170: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d  QLITE_FCNTL_RBU]
c180: 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65   opcode is imple
c190: 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 73 70  mented by the sp
c1a0: 65 63 69 61 6c 20 56 46 53 20 75 73 65 64 20 62  ecial VFS used b
c1b0: 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74  y.** the RBU ext
c1c0: 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c  ension only.  Al
c1d0: 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75  l other VFS shou
c1e0: 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ld return SQLITE
c1f0: 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a  _NOTFOUND for.**
c200: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a   this opcode.  .
c210: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c220: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
c230: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a  TOMIC_WRITE]].**
c240: 20 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   If the [SQLITE_
c250: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
c260: 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  IC_WRITE] opcode
c270: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
c280: 4f 4b 2c 20 74 68 61 74 0a 2a 2a 20 6d 65 61 6e  OK, that.** mean
c290: 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  s all subsequent
c2a0: 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e   write operation
c2b0: 73 20 77 69 6c 6c 20 62 65 20 64 65 66 65 72 72  s will be deferr
c2c0: 65 64 20 61 6e 64 20 64 6f 6e 65 0a 2a 2a 20 61  ed and done.** a
c2d0: 74 6f 6d 69 63 61 6c 6c 79 20 61 74 20 74 68 65  tomically at the
c2e0: 20 6e 65 78 74 20 5b 53 51 4c 49 54 45 5f 46 43   next [SQLITE_FC
c2f0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49  NTL_COMMIT_ATOMI
c300: 43 5f 57 52 49 54 45 5d 2e 20 20 53 79 73 74 65  C_WRITE].  Syste
c310: 6d 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 6e 6f  ms.** that do no
c320: 74 20 73 75 70 70 6f 72 74 20 62 61 74 63 68 20  t support batch 
c330: 61 74 6f 6d 69 63 20 77 72 69 74 65 73 20 77 69  atomic writes wi
c340: 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
c350: 5f 4e 4f 54 46 4f 55 4e 44 2e 0a 2a 2a 0a 2a 2a  _NOTFOUND..**.**
c360: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c370: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49  NTL_COMMIT_ATOMI
c380: 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 49 66 20  C_WRITE]].** If 
c390: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
c3a0: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
c3b0: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 63 61  WRITE] opcode ca
c3c0: 75 73 65 73 20 61 6c 6c 20 77 72 69 74 65 0a 2a  uses all write.*
c3d0: 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20 73 69 6e  * operations sin
c3e0: 63 65 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  ce the previous 
c3f0: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
c400: 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  to .** [SQLITE_F
c410: 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49  CNTL_BEGIN_ATOMI
c420: 43 5f 57 52 49 54 45 5d 20 74 6f 20 62 65 20 70  C_WRITE] to be p
c430: 65 72 66 6f 72 6d 65 64 20 61 74 6f 6d 69 63 61  erformed atomica
c440: 6c 6c 79 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c  lly..** This fil
c450: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
c460: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66  s [SQLITE_OK] if
c470: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
c480: 20 77 72 69 74 65 73 20 77 65 72 65 0a 2a 2a 20   writes were.** 
c490: 61 6c 6c 20 70 65 72 66 6f 72 6d 65 64 20 73 75  all performed su
c4a0: 63 63 65 73 73 66 75 6c 6c 79 20 61 6e 64 20 68  ccessfully and h
c4b0: 61 76 65 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74  ave been committ
c4c0: 65 64 20 74 6f 20 70 65 72 73 69 73 74 65 6e 74  ed to persistent
c4d0: 20 73 74 6f 72 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   storage..**.** 
c4e0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
c4f0: 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  TL_ROLLBACK_ATOM
c500: 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 49 66  IC_WRITE]].** If
c510: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
c520: 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  TL_ROLLBACK_ATOM
c530: 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  IC_WRITE] opcode
c540: 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74   causes all writ
c550: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20  e.** operations 
c560: 73 69 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f  since the previo
c570: 75 73 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  us successful ca
c580: 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54  ll to .** [SQLIT
c590: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54  E_FCNTL_BEGIN_AT
c5a0: 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62  OMIC_WRITE] to b
c5b0: 65 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 3c  e rollback..** <
c5c0: 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /ul>.*/.#define 
c5d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
c5e0: 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20  KSTATE          
c5f0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
c600: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f  QLITE_FCNTL_GET_
c610: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
c620: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
c630: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c  LITE_FCNTL_SET_L
c640: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
c650: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
c660: 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45  ITE_FCNTL_LAST_E
c670: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
c680: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
c690: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
c6a0: 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NT              
c6b0: 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
c6c0: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
c6d0: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
c6e0: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
c6f0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
c700: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37  TER            7
c710: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c720: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
c730: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a  ED            8.
c740: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c750: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
c760: 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23  TRY          9.#
c770: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c780: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20  NTL_PERSIST_WAL 
c790: 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
c7a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c7b0: 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  TL_OVERWRITE    
c7c0: 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65            11.#de
c7d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c7e0: 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20  L_VFSNAME       
c7f0: 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66           12.#def
c800: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c810: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
c820: 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69  RITE    13.#defi
c830: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c840: 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
c850: 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e         14.#defin
c860: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  e SQLITE_FCNTL_B
c870: 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20  USYHANDLER      
c880: 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65        15.#define
c890: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45   SQLITE_FCNTL_TE
c8a0: 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20  MPFILENAME      
c8b0: 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20       16.#define 
c8c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
c8d0: 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  P_SIZE          
c8e0: 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53      18.#define S
c8f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43  QLITE_FCNTL_TRAC
c900: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
c910: 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51     19.#define SQ
c920: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
c930: 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20 20  OVED            
c940: 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    20.#define SQL
c950: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20  ITE_FCNTL_SYNC  
c960: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c970: 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   21.#define SQLI
c980: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
c990: 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20 20  PHASETWO        
c9a0: 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  22.#define SQLIT
c9b0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45  E_FCNTL_WIN32_SE
c9c0: 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32  T_HANDLE       2
c9d0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
c9e0: 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b  _FCNTL_WAL_BLOCK
c9f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
ca00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ca10: 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 20  FCNTL_ZIPVFS    
ca20: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 0a               25.
ca30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
ca40: 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20 20  CNTL_RBU        
ca50: 20 20 20 20 20 20 20 20 20 20 20 20 32 36 0a 23              26.#
ca60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ca70: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20  NTL_VFS_POINTER 
ca80: 20 20 20 20 20 20 20 20 20 20 20 32 37 0a 23 64             27.#d
ca90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
caa0: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
cab0: 45 52 20 20 20 20 20 20 20 20 32 38 0a 23 64 65  ER        28.#de
cac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
cad0: 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44  L_WIN32_GET_HAND
cae0: 4c 45 20 20 20 20 20 20 20 32 39 0a 23 64 65 66  LE       29.#def
caf0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
cb00: 5f 50 44 42 20 20 20 20 20 20 20 20 20 20 20 20  _PDB            
cb10: 20 20 20 20 20 20 20 20 33 30 0a 23 64 65 66 69          30.#defi
cb20: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
cb30: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49  BEGIN_ATOMIC_WRI
cb40: 54 45 20 20 20 20 20 33 31 0a 23 64 65 66 69 6e  TE     31.#defin
cb50: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
cb60: 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49  OMMIT_ATOMIC_WRI
cb70: 54 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65  TE    32.#define
cb80: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f   SQLITE_FCNTL_RO
cb90: 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52  LLBACK_ATOMIC_WR
cba0: 49 54 45 20 20 33 33 0a 0a 2f 2a 20 64 65 70 72  ITE  33../* depr
cbb0: 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a  ecated names */.
cbc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
cbd0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
cbe0: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
cbf0: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
cc00: 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c  FILE.#define SQL
cc10: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
cc20: 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54  YFILE      SQLIT
cc30: 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b  E_FCNTL_SET_LOCK
cc40: 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e  PROXYFILE.#defin
cc50: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
cc60: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
cc70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53  SQLITE_FCNTL_LAS
cc80: 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20  T_ERRNO.../*.** 
cc90: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
cca0: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
ccb0: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
ccc0: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
ccd0: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
cce0: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
ccf0: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
cd00: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
cd10: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
cd20: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
cd30: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
cd40: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
cd50: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
cd60: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
cd70: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
cd80: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
cd90: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
cda0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
cdb0: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
cdc0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
cdd0: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
cde0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
cdf0: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
ce00: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
ce10: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ce20: 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73 69  Loadable Extensi
ce30: 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41  on Thunk.**.** A
ce40: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
ce50: 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f 61  opaque sqlite3_a
ce60: 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 75  pi_routines stru
ce70: 63 74 75 72 65 20 69 73 20 70 61 73 73 65 64 20  cture is passed 
ce80: 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20  as.** the third 
ce90: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e 74  parameter to ent
cea0: 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f  ry points of [lo
ceb0: 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e  adable extension
cec0: 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 72  s].  This.** str
ced0: 75 63 74 75 72 65 20 6d 75 73 74 20 62 65 20 74  ucture must be t
cee0: 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64 65  ypedefed in orde
cef0: 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  r to work around
cf00: 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e   compiler warnin
cf10: 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c  gs.** on some pl
cf20: 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65  atforms..*/.type
cf30: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
cf40: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20  e3_api_routines 
cf50: 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74  sqlite3_api_rout
cf60: 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ines;../*.** CAP
cf70: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
cf80: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
cf90: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
cfa0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
cfb0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
cfc0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
cfd0: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
cfe0: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
cff0: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
d000: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
d010: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
d020: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
d030: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
d040: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
d050: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
d060: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
d070: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
d080: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
d090: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
d0a0: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
d0b0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
d0c0: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
d0d0: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
d0e0: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
d0f0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
d100: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
d110: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
d120: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
d130: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
d140: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
d150: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
d160: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
d170: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
d180: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
d190: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
d1a0: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
d1b0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
d1c0: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
d1d0: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
d1e0: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
d1f0: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
d200: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
d210: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
d220: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
d230: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
d240: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
d250: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
d260: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
d270: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
d280: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
d290: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
d2a0: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
d2b0: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
d2c0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
d2d0: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
d2e0: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
d2f0: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
d300: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
d310: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
d320: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
d330: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
d340: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
d350: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
d360: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
d370: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
d380: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
d390: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
d3a0: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
d3b0: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
d3c0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
d3d0: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
d3e0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
d3f0: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
d400: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
d410: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
d420: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
d430: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
d440: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
d450: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
d460: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
d470: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
d480: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
d490: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
d4a0: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
d4b0: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
d4c0: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
d4d0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
d4e0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
d4f0: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
d500: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
d510: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
d520: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
d530: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
d540: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
d550: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
d560: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
d570: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
d580: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
d590: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
d5a0: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
d5b0: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  s..**.** [[sqlit
d5c0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a  e3_vfs.xOpen]].*
d5d0: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
d5e0: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46  tees that the zF
d5f0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
d600: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
d610: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
d620: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
d630: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
d640: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
d650: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e  ) with an option
d660: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e  al suffix added.
d670: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78  .** ^If a suffix
d680: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
d690: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
d6a0: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a  eter, it will.**
d6b0: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69   consist of a si
d6c0: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74  ngle "-" charact
d6d0: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e  er followed by n
d6e0: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31  o more than.** 1
d6f0: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61  1 alphanumeric a
d700: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63  nd/or "-" charac
d710: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ters..** ^SQLite
d720: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
d730: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
d740: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
d750: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
d760: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
d770: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
d780: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
d790: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
d7a0: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
d7b0: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
d7c0: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
d7d0: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
d7e0: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
d7f0: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
d800: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
d810: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
d820: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
d830: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
d840: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
d850: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
d860: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69  ** must invent i
d870: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
d880: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
d890: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74  le.  ^Whenever t
d8a0: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
d8b0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
d8c0: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
d8d0: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
d8e0: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
d8f0: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
d900: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
d910: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
d920: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
d930: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
d940: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
d950: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
d960: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
d970: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
d980: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
d990: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
d9a0: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
d9b0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
d9c0: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
d9d0: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
d9e0: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
d9f0: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
da00: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
da10: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
da20: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
da30: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
da40: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
da50: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
da60: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
da70: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
da80: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
da90: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
daa0: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
dab0: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
dac0: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
dad0: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
dae0: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
daf0: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
db00: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
db10: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
db20: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
db30: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
db40: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
db50: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
db60: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
db70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
db80: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
db90: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
dba0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
dbb0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
dbc0: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
dbd0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
dbe0: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
dbf0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
dc00: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
dc10: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
dc20: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a  LITE_OPEN_WAL].*
dc30: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
dc40: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
dc50: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
dc60: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
dc70: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
dc80: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
dc90: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
dca0: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
dcb0: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
dcc0: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
dcd0: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
dce0: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
dcf0: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
dd00: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
dd10: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
dd20: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
dd30: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
dd40: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
dd50: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
dd60: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
dd70: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
dd80: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
dd90: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
dda0: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
ddb0: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
ddc0: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
ddd0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
dde0: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
ddf0: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
de00: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
de10: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
de20: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
de30: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
de40: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
de50: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
de60: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
de70: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
de80: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
de90: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
dea0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
deb0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
dec0: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
ded0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
dee0: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
def0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  >.**.** The [SQL
df00: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
df10: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
df20: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
df30: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
df40: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
df50: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ed.  ^The [SQLIT
df60: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
df70: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
df80: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61   set for TEMP da
df90: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69  tabases and thei
dfa0: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e  r journals, tran
dfb0: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73  sient.** databas
dfc0: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e  es, and subjourn
dfd0: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  als..**.** ^The 
dfe0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
dff0: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20  LUSIVE] flag is 
e000: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63  always used in c
e010: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  onjunction.** wi
e020: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
e030: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67  PEN_CREATE] flag
e040: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68  , which are both
e050: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61   directly.** ana
e060: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f  logous to the O_
e070: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54  EXCL and O_CREAT
e080: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f   flags of the PO
e090: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50  SIX open().** AP
e0a0: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  I.  The SQLITE_O
e0b0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c  PEN_EXCLUSIVE fl
e0c0: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20  ag, when paired 
e0d0: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
e0e0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c  ITE_OPEN_CREATE,
e0f0: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69   is used to indi
e100: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73  cate that file s
e110: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20  hould always.** 
e120: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20  be created, and 
e130: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72  that it is an er
e140: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64  ror if it alread
e150: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20  y exists..** It 
e160: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73  is <i>not</i> us
e170: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
e180: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
e190: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72  e opened .** for
e1a0: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
e1b0: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61  s..**.** ^At lea
e1c0: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
e1d0: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
e1e0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
e1f0: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
e200: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
e210: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
e220: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
e230: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
e240: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65  xOpen.  The xOpe
e250: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
e260: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
e270: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
e280: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
e290: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20  ust fill it in. 
e2a0: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68   Note that.** th
e2b0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d  e xOpen method m
e2c0: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69  ust set the sqli
e2d0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
e2e0: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61  s to either.** a
e2f0: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f   valid [sqlite3_
e300: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
e310: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20  ct or to NULL.  
e320: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a  xOpen must do.**
e330: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68   this even if th
e340: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53  e open fails.  S
e350: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68  QLite expects th
e360: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  at the sqlite3_f
e370: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20  ile.pMethods.** 
e380: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  element will be 
e390: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65  valid after xOpe
e3a0: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64  n returns regard
e3b0: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
e3c0: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72  ess.** or failur
e3d0: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63  e of the xOpen c
e3e0: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  all..**.** [[sql
e3f0: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73  ite3_vfs.xAccess
e400: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73  ]].** ^The flags
e410: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
e420: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
e430: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
e440: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
e450: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
e460: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
e470: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
e480: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
e490: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
e4a0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
e4b0: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
e4c0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
e4d0: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
e4e0: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
e4f0: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
e500: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
e510: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
e520: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53  ectory..**.** ^S
e530: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
e540: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
e550: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
e560: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
e570: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
e580: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
e590: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
e5a0: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
e5b0: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
e5c0: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
e5d0: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
e5e0: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
e5f0: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
e600: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
e610: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
e620: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
e630: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
e640: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
e650: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
e660: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
e670: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
e680: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
e690: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
e6a0: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
e6b0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
e6c0: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
e6d0: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
e6e0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
e6f0: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43  (), xSleep(), xC
e700: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e  urrentTime(), an
e710: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  d xCurrentTimeIn
e720: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  t64().** interfa
e730: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69  ces are not stri
e740: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
e750: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
e760: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
e770: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
e780: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
e790: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
e7a0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
e7b0: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
e7c0: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
e7d0: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
e7e0: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
e7f0: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
e800: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
e810: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
e820: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
e830: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
e840: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
e850: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
e860: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
e870: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
e880: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
e890: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
e8a0: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
e8b0: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54  conds given.  ^T
e8c0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
e8d0: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
e8e0: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
e8f0: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
e900: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
e910: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c   time as.** a fl
e920: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
e930: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72  ue..** ^The xCur
e940: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
e950: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
e960: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
e970: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
e980: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69   Number multipli
e990: 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28  ed by 86400000 (
e9a0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
e9b0: 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a  lliseconds in .*
e9c0: 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29  * a 24-hour day)
e9d0: 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .  .** ^SQLite w
e9e0: 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72  ill use the xCur
e9f0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
ea00: 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68  method to get th
ea10: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74  e current.** dat
ea20: 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68  e and time if th
ea30: 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61  at method is ava
ea40: 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73  ilable (if iVers
ea50: 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20  ion is 2 or .** 
ea60: 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20  greater and the 
ea70: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
ea80: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e   is not NULL) an
ea90: 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b  d will fall back
eaa0: 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54  .** to xCurrentT
eab0: 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e  ime() if xCurren
eac0: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20  tTimeInt64() is 
ead0: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a  unavailable..**.
eae0: 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74  ** ^The xSetSyst
eaf0: 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79  emCall(), xGetSy
eb00: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20  stemCall(), and 
eb10: 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28  xNestSystemCall(
eb20: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
eb30: 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20  are not used by 
eb40: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e  the SQLite core.
eb50: 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c    These optional
eb60: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
eb70: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73  provided.** by s
eb80: 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63  ome VFSes to fac
eb90: 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20  ilitate testing 
eba0: 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e  of the VFS code.
ebb0: 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a   By overriding .
ebc0: 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  ** system calls 
ebd0: 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75  with functions u
ebe0: 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c  nder its control
ebf0: 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d  , a test program
ec00: 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65   can.** simulate
ec10: 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f   faults and erro
ec20: 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61  r conditions tha
ec30: 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73  t would otherwis
ec40: 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a  e be difficult.*
ec50: 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20  * or impossible 
ec60: 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20  to induce.  The 
ec70: 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61  set of system ca
ec80: 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  lls that can be 
ec90: 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61  overridden.** va
eca0: 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46  ries from one VF
ecb0: 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e  S to another, an
ecc0: 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69  d from one versi
ecd0: 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56  on of the same V
ece0: 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78  FS to the.** nex
ecf0: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
ed00: 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20   that use these 
ed10: 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20  interfaces must 
ed20: 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20  be prepared for 
ed30: 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66  any.** or all of
ed40: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
ed50: 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20  s to be NULL or 
ed60: 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69  for their behavi
ed70: 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  or to change.** 
ed80: 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65  from one release
ed90: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41   to the next.  A
eda0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
edb0: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20   not attempt to 
edc0: 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66  access.** any of
edd0: 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69   these methods i
ede0: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f  f the iVersion o
edf0: 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73  f the VFS is les
ee00: 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70  s than 3..*/.typ
ee10: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
ee20: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
ee30: 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69  vfs;.typedef voi
ee40: 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63  d (*sqlite3_sysc
ee50: 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a  all_ptr)(void);.
ee60: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
ee70: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
ee80: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
ee90: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
eea0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
eeb0: 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69  rently 3) */.  i
eec0: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
eed0: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
eee0: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
eef0: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
ef00: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
ef10: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
ef20: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
ef30: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
ef40: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
ef50: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
ef60: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
ef70: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
ef80: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
ef90: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
efa0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
efb0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
efc0: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
efd0: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
efe0: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
eff0: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
f000: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
f010: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
f020: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
f030: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
f040: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
f050: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
f060: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
f070: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
f080: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
f090: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
f0a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
f0b0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
f0c0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
f0d0: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
f0e0: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
f0f0: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
f100: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
f110: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
f120: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
f130: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
f140: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
f150: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
f160: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
f170: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
f180: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
f190: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
f1a0: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
f1b0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
f1c0: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
f1d0: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
f1e0: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
f1f0: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
f200: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
f210: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
f220: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
f230: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
f240: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
f250: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
f260: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
f270: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
f280: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
f290: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
f2a0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
f2b0: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
f2c0: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
f2d0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
f2e0: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
f2f0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
f300: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
f310: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
f320: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
f330: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
f340: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
f350: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
f360: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
f370: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
f380: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
f390: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
f3a0: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
f3b0: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
f3c0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
f3d0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
f3e0: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
f3f0: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
f400: 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62  ct..  ** Those b
f410: 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72  elow are for ver
f420: 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74  sion 3 and great
f430: 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  er..  */.  int (
f440: 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xSetSystemCall)
f450: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
f460: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
f470: 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  , sqlite3_syscal
f480: 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65  l_ptr);.  sqlite
f490: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a  3_syscall_ptr (*
f4a0: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xGetSystemCall)(
f4b0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
f4c0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
f4d0: 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ;.  const char *
f4e0: 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c  (*xNextSystemCal
f4f0: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
f500: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
f510: 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  me);.  /*.  ** T
f520: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
f530: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
f540: 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20   1 through 3 of 
f550: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
f560: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20  bject..  ** New 
f570: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
f580: 70 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72 65  pended in future
f590: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
f5a0: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
f5b0: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
f5c0: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
f5d0: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a   happens. .  */.
f5e0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
f5f0: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
f600: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
f610: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
f620: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
f630: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
f640: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
f650: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
f660: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
f670: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
f680: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
f690: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
f6a0: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
f6b0: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
f6c0: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
f6d0: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
f6e0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
f6f0: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
f700: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
f710: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
f720: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
f730: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
f740: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
f750: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
f760: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
f770: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e  ks whether the n
f780: 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69  amed directory i
f790: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
f7a0: 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20  and writable.** 
f7b0: 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  (in other words,
f7c0: 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65   if files can be
f7d0: 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c   added, removed,
f7e0: 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74   and renamed wit
f7f0: 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63  hin.** the direc
f800: 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51  tory)..** The SQ
f810: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f820: 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69  WRITE constant i
f830: 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64  s currently used
f840: 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20   only by the.** 
f850: 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
f860: 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74  ctory pragma], t
f870: 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64  hough this could
f880: 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
f890: 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
f8a0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74  f SQLite..** Wit
f8b0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
f8c0: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
f8d0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
f8e0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
f8f0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
f900: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43    The SQLITE_ACC
f910: 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e  ESS_READ constan
f920: 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c  t is.** currentl
f930: 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68  y unused, though
f940: 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65   it might be use
f950: 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  d in a future re
f960: 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
f970: 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
f980: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
f990: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
f9a0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
f9b0: 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20  EADWRITE 1   /* 
f9c0: 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74  Used by PRAGMA t
f9d0: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
f9e0: 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ory */.#define S
f9f0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
fa00: 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e  D      2   /* Un
fa10: 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
fa20: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
fa30: 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  or the xShmLock 
fa40: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
fa50: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
fa60: 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
fa70: 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b  the various lock
fa80: 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ing operations.*
fa90: 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65  * allowed by the
faa0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
fab0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   of [sqlite3_io_
fac0: 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a  methods].  The.*
fad0: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20  * following are 
fae0: 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63  the only legal c
faf0: 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66  ombinations of f
fb00: 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  lags to the.** x
fb10: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a  ShmLock method:.
fb20: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
fb30: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
fb40: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
fb50: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
fb60: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
fb70: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
fb80: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CLUSIVE.** <li> 
fb90: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
fba0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
fbb0: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
fbc0: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
fbd0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
fbe0: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c  XCLUSIVE.** </ul
fbf0: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c  >.**.** When unl
fc00: 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65  ocking, the same
fc10: 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55   SHARED or EXCLU
fc20: 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62  SIVE flag must b
fc30: 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a  e supplied as.**
fc40: 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68   was given on th
fc50: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
fc60: 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  lock.  .**.** Th
fc70: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
fc80: 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e  d can transition
fc90: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
fca0: 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a  d and SHARED or.
fcb0: 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  ** between unloc
fcc0: 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56  ked and EXCLUSIV
fcd0: 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72  E.  It cannot tr
fce0: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
fcf0: 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45   SHARED.** and E
fd00: 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65  XCLUSIVE..*/.#de
fd10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
fd20: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23  UNLOCK       1.#
fd30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
fd40: 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32  M_LOCK         2
fd50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
fd60: 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20  SHM_SHARED      
fd70: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
fd80: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20  E_SHM_EXCLUSIVE 
fd90: 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     8../*.** CAPI
fda0: 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53  3REF: Maximum xS
fdb0: 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a  hmLock index.**.
fdc0: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
fdd0: 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74  method on [sqlit
fde0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d  e3_io_methods] m
fdf0: 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a  ay use values.**
fe00: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
fe10: 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20  his upper bound 
fe20: 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20  as its "offset" 
fe30: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
fe40: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
fe50: 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20  l never attempt 
fe60: 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65  to acquire or re
fe70: 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20  lease a.** lock 
fe80: 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20  outside of this 
fe90: 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65  range.*/.#define
fea0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43   SQLITE_SHM_NLOC
feb0: 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  K        8.../*.
fec0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69  ** CAPI3REF: Ini
fed0: 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69  tialize The SQLi
fee0: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
fef0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
ff00: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
ff10: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
ff20: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
ff30: 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69  rary.  ^The sqli
ff40: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
ff50: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
ff60: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
ff70: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
ff80: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
ff90: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
ffa0: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
ffb0: 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20  es are designed 
ffc0: 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73  to aid in proces
ffd0: 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
ffe0: 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e   and.** shutdown
fff0: 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73   on embedded sys
10000 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69  tems.  Workstati
10010 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  on applications 
10020 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20  using.** SQLite 
10030 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20  normally do not 
10040 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65  need to invoke e
10050 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72  ither of these r
10060 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  outines..**.** A
10070 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
10080 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
10090 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
100a0 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a  call if it is.**
100b0 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
100c0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
100d0 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ze() is invoked 
100e0 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
100f0 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72  ime of.** the pr
10100 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20  ocess, or if it 
10110 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  is the first tim
10120 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
10130 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
10140 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  d.** following a
10150 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
10160 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28  _shutdown().  ^(
10170 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76  Only an effectiv
10180 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c  e call.** of sql
10190 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
101a0 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69  ) does any initi
101b0 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20  alization.  All 
101c0 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61  other calls.** a
101d0 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
101e0 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ps.)^.**.** A ca
101f0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
10200 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22  utdown() is an "
10210 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
10220 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
10230 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  st.** call to sq
10240 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10250 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
10260 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10270 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a  ze().  ^(Only.**
10280 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
10290 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
102a0 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e  utdown() does an
102b0 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69  y deinitializati
102c0 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72  on..** All other
102d0 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20   valid calls to 
102e0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
102f0 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  () are harmless 
10300 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
10310 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
10320 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61  ialize() interfa
10330 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ce is threadsafe
10340 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68  , but sqlite3_sh
10350 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e  utdown().** is n
10360 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ot.  The sqlite3
10370 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65  _shutdown() inte
10380 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20  rface must only 
10390 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  be called from a
103a0 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61  .** single threa
103b0 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61  d.  All open [da
103c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
103d0 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73  ns] must be clos
103e0 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74  ed and all.** ot
103f0 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75  her SQLite resou
10400 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61  rces must be dea
10410 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74  llocated prior t
10420 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71  o invoking.** sq
10430 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10440 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74  ..**.** Among ot
10450 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c  her things, ^sql
10460 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10470 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a  ) will invoke.**
10480 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
10490 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20  ().  Similarly, 
104a0 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  ^sqlite3_shutdow
104b0 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f  n().** will invo
104c0 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ke sqlite3_os_en
104d0 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  d()..**.** ^The 
104e0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
104f0 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
10500 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
10510 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
10520 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ^If for some rea
10530 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
10540 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
10550 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
10560 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
10570 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
10580 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
10590 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
105a0 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
105b0 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
105c0 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
105d0 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
105e0 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
105f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
10600 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
10610 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
10620 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
10630 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
10640 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
10650 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
10660 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
10670 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
10680 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
10690 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
106a0 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
106b0 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
106c0 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
106d0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
106e0 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
106f0 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
10700 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
10710 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
10720 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
10730 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
10740 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
10750 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
10760 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c  eady.  ^However,
10770 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
10780 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
10790 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
107a0 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  OINIT].** compil
107b0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74  e-time option, t
107c0 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69  hen the automati
107d0 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  c calls to sqlit
107e0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
107f0 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61  ** are omitted a
10800 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
10810 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c  on must call sql
10820 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10830 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72  ) directly.** pr
10840 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
10850 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
10860 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61  terface.  For ma
10870 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74  ximum portabilit
10880 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f  y,.** it is reco
10890 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
108a0 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73  lications always
108b0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
108c0 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
108d0 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74  directly prior t
108e0 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
108f0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
10900 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65  ce.  Future rele
10910 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ases.** of SQLit
10920 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68  e may require th
10930 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  is.  In other wo
10940 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f  rds, the behavio
10950 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77  r exhibited.** w
10960 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
10970 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
10980 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
10990 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20  T] might become 
109a0 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62  the.** default b
109b0 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20  ehavior in some 
109c0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
109d0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
109e0 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
109f0 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  nit() routine do
10a00 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  es operating-sys
10a10 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  tem specific.** 
10a20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
10a30 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
10a40 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
10a50 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72  e3_os_end().** r
10a60 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68  outine undoes th
10a70 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69  e effect of sqli
10a80 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
10a90 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a  Typical tasks.**
10aa0 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68   performed by th
10ab0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63  ese routines inc
10ac0 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  lude allocation 
10ad0 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  or deallocation.
10ae0 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73  ** of static res
10af0 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69  ources, initiali
10b00 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c  zation of global
10b10 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73   variables,.** s
10b20 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61  etting up a defa
10b30 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
10b40 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74  ] module, or set
10b50 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66  ting up.** a def
10b60 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
10b70 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  on using [sqlite
10b80 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a  3_config()]..**.
10b90 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
10ba0 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
10bb0 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71  invoke either sq
10bc0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
10bd0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  ** or sqlite3_os
10be0 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e  _end() directly.
10bf0 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
10c00 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e  n should only in
10c10 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
10c20 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
10c30 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10c40 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65  n().  The sqlite
10c50 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69  3_os_init().** i
10c60 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c  nterface is call
10c70 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
10c80 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
10c90 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20  ialize() and.** 
10ca0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
10cb0 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71   is called by sq
10cc0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10cd0 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a  .  Appropriate.*
10ce0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
10cf0 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  s for sqlite3_os
10d00 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
10d10 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
10d20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  are built into S
10d30 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73  QLite when it is
10d40 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e   compiled for Un
10d50 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20  ix, Windows, or 
10d60 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63  OS/2..** When [c
10d70 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62  ustom builds | b
10d80 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
10d90 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73  latforms].** (us
10da0 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
10db0 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70  OS_OTHER=1] comp
10dc0 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
10dd0 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
10de0 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
10df0 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
10e00 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
10e10 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
10e20 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
10e30 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
10e40 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
10e50 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
10e60 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
10e70 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
10e80 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
10e90 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c  must return [SQL
10ea0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
10eb0 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
10ec0 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
10ed0 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
10ee0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69  */.int sqlite3_i
10ef0 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
10f00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75  .int sqlite3_shu
10f10 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74  tdown(void);.int
10f20 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
10f30 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
10f40 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
10f50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10f60 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
10f70 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
10f80 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  y.**.** The sqli
10f90 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
10fa0 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
10fb0 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f  o make global co
10fc0 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
10fd0 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65  hanges to SQLite
10fe0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e   in order to tun
10ff0 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  e SQLite to the 
11000 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
11010 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
11020 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75  tion.  The defau
11030 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
11040 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
11050 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c  for most.** appl
11060 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20  ications and so 
11070 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
11080 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65  usually not nece
11090 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a  ssary.  It is.**
110a0 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70   provided to sup
110b0 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63  port rare applic
110c0 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73  ations with unus
110d0 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ual needs..**.**
110e0 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33 5f   <b>The sqlite3_
110f0 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
11100 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  ce is not thread
11110 73 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69 63  safe. The applic
11120 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e  ation.** must en
11130 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
11140 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
11150 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
11160 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
11170 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
11180 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
11190 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a  unning.</b>.**.*
111a0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
111b0 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
111c0 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
111d0 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
111e0 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
111f0 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
11200 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
11210 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
11220 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
11230 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11240 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
11250 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
11260 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
11270 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11280 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
11290 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
112a0 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
112b0 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
112c0 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
112d0 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
112e0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
112f0 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
11300 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
11310 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
11320 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
11330 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
11340 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
11350 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
11360 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
11370 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
11380 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f  n integer.** [co
11390 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
113a0 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
113b0 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
113c0 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
113d0 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
113e0 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
113f0 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
11400 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
11410 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  he [configuratio
11420 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
11430 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
11440 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
11450 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
11460 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
11470 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
11480 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
11490 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
114a0 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
114b0 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
114c0 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
114d0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
114e0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
114f0 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
11500 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
11510 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  .int sqlite3_con
11520 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
11530 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11540 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
11550 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
11560 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
11570 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  3.**.** The sqli
11580 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
11590 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
115a0 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67  d to make config
115b0 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
115c0 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73  es to a [databas
115d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
115e0 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73  The interface is
115f0 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b   similar to.** [
11600 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11610 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  ] except that th
11620 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20  e changes apply 
11630 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  to a single.** [
11640 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11650 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20  ion] (specified 
11660 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
11670 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  ument)..**.** Th
11680 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
11690 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f  t to sqlite3_db_
116a0 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20  config(D,V,...) 
116b0 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   is the.** [SQLI
116c0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
116d0 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72  ASIDE | configur
116e0 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e  ation verb] - an
116f0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a   integer code .*
11700 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  * that indicates
11710 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20   what aspect of 
11720 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
11730 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
11740 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a  ng configured..*
11750 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67  * Subsequent arg
11760 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65  uments vary depe
11770 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e  nding on the con
11780 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e  figuration verb.
11790 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  .**.** ^Calls to
117a0 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
117b0 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49  ig() return SQLI
117c0 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c  TE_OK if and onl
117d0 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  y if.** the call
117e0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73   is considered s
117f0 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e  uccessful..*/.in
11800 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  t sqlite3_db_con
11810 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  fig(sqlite3*, in
11820 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  t op, ...);../*.
11830 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
11840 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52  ory Allocation R
11850 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e  outines.**.** An
11860 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
11870 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
11880 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
11890 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  etween SQLite.**
118a0 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d   and low-level m
118b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
118c0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
118d0 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
118e0 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65  used in only one
118f0 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51   place in the SQ
11900 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
11910 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
11920 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
11930 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68  his object is th
11940 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  e argument to.**
11950 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11960 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e  ()] when the con
11970 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11980 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  n is.** [SQLITE_
11990 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f  CONFIG_MALLOC] o
119a0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
119b0 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a  _GETMALLOC].  .*
119c0 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e  * By creating an
119d0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
119e0 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20  s object.** and 
119f0 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
11a00 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
11a10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
11a20 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67  LLOC]).** during
11a30 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
11a40 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  an application c
11a50 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
11a60 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
11a70 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
11a80 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c  ubsystem for SQL
11a90 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
11aa0 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e  ll of its.** dyn
11ab0 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64  amic memory need
11ac0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
11ad0 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20  at SQLite comes 
11ae0 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75  with several [bu
11af0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
11b00 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61  locators].** tha
11b10 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20  t are perfectly 
11b20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65  adequate for the
11b30 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61   overwhelming ma
11b40 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  jority of applic
11b50 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68  ations.** and th
11b60 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  at this object i
11b70 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f  s only useful to
11b80 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79   a tiny minority
11b90 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
11ba0 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c  .** with special
11bb0 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ized memory allo
11bc0 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65  cation requireme
11bd0 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  nts.  This objec
11be0 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65  t is.** also use
11bf0 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
11c00 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   of SQLite in or
11c10 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  der to specify a
11c20 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
11c30 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
11c40 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73  r that simulates
11c50 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d   memory out-of-m
11c60 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73  emory conditions
11c70 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20   in.** order to 
11c80 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69  verify that SQLi
11c90 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63  te recovers grac
11ca0 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68  efully from such
11cb0 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a  .** conditions..
11cc0 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f  **.** The xMallo
11cd0 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64  c, xRealloc, and
11ce0 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d   xFree methods m
11cf0 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68  ust work like th
11d00 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72  e.** malloc(), r
11d10 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  ealloc() and fre
11d20 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72  e() functions fr
11d30 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
11d40 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53  C library..** ^S
11d50 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
11d60 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
11d70 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
11d80 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61  xRealloc is alwa
11d90 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72  ys a value retur
11da0 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63  ned by a prior c
11db0 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e  all to xRoundup.
11dc0 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f  .**.** xSize sho
11dd0 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61  uld return the a
11de0 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
11df0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
11e00 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73  tion.** previous
11e10 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
11e20 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61   xMalloc or xRea
11e30 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63  lloc.  The alloc
11e40 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20  ated size.** is 
11e50 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20  always at least 
11e60 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65  as big as the re
11e70 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74  quested size but
11e80 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a   may be larger..
11e90 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64  **.** The xRound
11ea0 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  up method return
11eb0 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20  s what would be 
11ec0 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
11ed0 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72  ze of.** a memor
11ee0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76  y allocation giv
11ef0 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  en a particular 
11f00 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20  requested size. 
11f10 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   Most memory.** 
11f20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
11f30 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   up memory alloc
11f40 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20  ations at least 
11f50 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74  to the next mult
11f60 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53  iple.** of 8.  S
11f70 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  ome allocators r
11f80 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72  ound up to a lar
11f90 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20  ger multiple or 
11fa0 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e  to a power of 2.
11fb0 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79  .** Every memory
11fc0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
11fd0 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68  est coming in th
11fe0 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d  rough [sqlite3_m
11ff0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b  alloc()].** or [
12000 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
12010 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78  )] first calls x
12020 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f  Roundup.  If xRo
12030 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c  undup returns 0,
12040 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73   .** that causes
12050 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
12060 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ng memory alloca
12070 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a  tion to fail..**
12080 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65  .** The xInit me
12090 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73  thod initializes
120a0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
120b0 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d  cator.  For exam
120c0 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
120d0 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
120e0 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
120f0 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
12100 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
12110 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
12120 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
12130 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
12140 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
12150 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
12160 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
12170 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
12180 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
12190 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
121a0 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
121b0 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
121c0 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
121d0 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
121e0 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a  xShutdown..**.**
121f0 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68   SQLite holds th
12200 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
12210 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d  STATIC_MASTER] m
12220 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76  utex when it inv
12230 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69  okes.** the xIni
12240 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65  t method, so the
12250 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65   xInit method ne
12260 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ed not be thread
12270 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53  safe.  The.** xS
12280 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
12290 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72  s only called fr
122a0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  om [sqlite3_shut
122b0 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f  down()] so it do
122c0 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74  es.** not need t
122d0 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  o be threadsafe 
122e0 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c  either.  For all
122f0 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20   other methods, 
12300 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20  SQLite.** holds 
12310 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
12320 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75  X_STATIC_MEM] mu
12330 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  tex as long as t
12340 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
12350 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
12360 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12370 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
12380 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69  n (which.** it i
12390 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e  s by default) an
123a0 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73  d so the methods
123b0 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
123c0 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a  ly serialized..*
123d0 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53  * However, if [S
123e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
123f0 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62  STATUS] is disab
12400 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74  led, then the ot
12410 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d  her.** methods m
12420 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
12430 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74  e or else make t
12440 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65  heir own arrange
12450 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72  ments for.** ser
12460 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ialization..**.*
12470 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
12480 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74  ver invoke xInit
12490 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  () more than onc
124a0 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74  e without an int
124b0 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c  ervening.** call
124c0 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e   to xShutdown().
124d0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
124e0 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
124f0 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
12500 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  em_methods;.stru
12510 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
12520 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20  ethods {.  void 
12530 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29  *(*xMalloc)(int)
12540 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d  ;         /* Mem
12550 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
12560 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
12570 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a  d (*xFree)(void*
12580 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46  );          /* F
12590 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f  ree a prior allo
125a0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  cation */.  void
125b0 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f   *(*xRealloc)(vo
125c0 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65  id*,int);  /* Re
125d0 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69  size an allocati
125e0 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  on */.  int (*xS
125f0 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ize)(void*);    
12600 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e         /* Return
12610 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20   the size of an 
12620 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
12630 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28  int (*xRoundup)(
12640 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f  int);          /
12650 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65  * Round up reque
12660 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63  st size to alloc
12670 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
12680 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69  int (*xInit)(voi
12690 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
126a0 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  * Initialize the
126b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
126c0 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53  r */.  void (*xS
126d0 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b  hutdown)(void*);
126e0 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69        /* Deiniti
126f0 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
12700 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
12710 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
12720 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
12730 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49  * Argument to xI
12740 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64  nit() and xShutd
12750 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  own() */.};../*.
12760 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
12770 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
12780 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
12790 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  {configuration o
127a0 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ption}.**.** The
127b0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
127c0 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
127d0 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
127e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
127f0 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
12800 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
12810 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
12820 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12830 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
12840 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
12850 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
12860 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
12870 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
12880 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
12890 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
128a0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
128b0 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
128c0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
128d0 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
128e0 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
128f0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
12900 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
12910 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
12920 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
12930 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
12940 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
12950 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
12960 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
12970 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
12980 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
12990 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
129a0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
129b0 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
129c0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
129d0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
129e0 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
129f0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
12a00 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ETHREAD</dt>.** 
12a10 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
12a20 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
12a30 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
12a40 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
12a50 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
12a60 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d  mode] to Single-
12a70 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
12a80 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
12a90 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
12aa0 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51  xing and puts SQ
12ab0 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65  Lite into a mode
12ac0 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e   where it can on
12ad0 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79  ly be used.** by
12ae0 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
12af0 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
12b00 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
12b10 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
12b20 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
12b30 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
12b40 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
12b50 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
12b60 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
12b70 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74  to change the [t
12b80 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66  hreading mode] f
12b90 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a  rom its default.
12ba0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67  ** value of Sing
12bb0 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f  le-thread and so
12bc0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12bd0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
12be0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
12bf0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
12c00 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
12c10 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
12c20 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
12c30 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
12c40 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12c50 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
12c60 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12c70 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
12c80 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
12c90 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
12ca0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
12cb0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
12cc0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
12cd0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
12ce0 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20  o Multi-thread. 
12cf0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
12d00 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
12d10 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74  mutexing on [dat
12d20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12d30 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
12d40 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
12d50 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ts..** The appli
12d60 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e  cation is respon
12d70 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c  sible for serial
12d80 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a  izing access to.
12d90 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
12da0 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
12db0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
12dc0 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20  ts].  But other 
12dd0 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
12de0 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53  nabled so that S
12df0 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61  QLite will be sa
12e00 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d  fe to use in a m
12e10 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ulti-threaded.**
12e20 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20   environment as 
12e30 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74  long as no two t
12e40 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74  hreads attempt t
12e50 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a  o use the same.*
12e60 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
12e70 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73  ection] at the s
12e80 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53  ame time.  ^If S
12e90 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
12ea0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
12eb0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12ec0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
12ed0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
12ee0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
12ef0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
12f00 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
12f10 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e Multi-thread [
12f20 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
12f30 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
12f40 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
12f50 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
12f60 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
12f70 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
12f80 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
12f90 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69  READ configurati
12fa0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
12fb0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12fc0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
12fd0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12fe0 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c  NFIG_SERIALIZED<
12ff0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
13000 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
13010 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
13020 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
13030 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
13040 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
13050 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20   Serialized. In 
13060 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69  other words, thi
13070 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73  s option enables
13080 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20  .** all mutexes 
13090 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65  including the re
130a0 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78  cursive.** mutex
130b0 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  es on [database 
130c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
130d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
130e0 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
130f0 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77   In this mode (w
13100 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61  hich is the defa
13110 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ult when SQLite 
13120 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13130 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
13140 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53  ADSAFE=1]) the S
13150 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
13160 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c  ll itself serial
13170 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ize access.** to
13180 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13190 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
131a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
131b0 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a  ] so that the.**
131c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
131d0 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20  free to use the 
131e0 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
131f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68  onnection] or th
13200 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61  e.** same [prepa
13210 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
13220 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  n different thre
13230 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
13240 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c  time..** ^If SQL
13250 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
13260 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
13270 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
13280 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
13290 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
132a0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
132b0 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
132c0 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
132d0 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  Serialized [thre
132e0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
132f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
13300 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
13310 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
13320 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
13330 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
13340 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
13350 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13360 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
13370 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13380 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  _MALLOC]] <dt>SQ
13390 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
133a0 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
133b0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
133c0 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f  FIG_MALLOC optio
133d0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
133e0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
133f0 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  is .** a pointer
13400 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
13410 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
13420 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
13430 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61  ucture..** The a
13440 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
13450 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
13460 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
13470 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
13480 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
13490 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20   in place of.** 
134a0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
134b0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62  ation routines b
134c0 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
134d0 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  .)^ ^SQLite make
134e0 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69  s.** its own pri
134f0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
13500 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
13510 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
13520 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a  hods] structure.
13530 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73  ** before the [s
13540 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
13550 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f   call returns.</
13560 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13570 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
13580 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
13590 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
135a0 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
135b0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
135c0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74  IG_GETMALLOC opt
135d0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
135e0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
135f0 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
13600 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
13610 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
13620 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
13630 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
13640 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
13650 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
13660 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
13670 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
13680 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61  defined memory a
13690 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
136a0 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
136b0 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
136c0 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
136d0 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
136e0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
136f0 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
13700 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c  apper that simul
13710 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c  ations memory al
13720 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
13730 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65   or.** tracks me
13740 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20  mory usage, for 
13750 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a  example. </dd>.*
13760 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13770 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d  NFIG_MEMSTATUS]]
13780 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13790 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74  IG_MEMSTATUS</dt
137a0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
137b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
137c0 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61  STATUS option ta
137d0 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  kes single argum
137e0 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c  ent of type int,
137f0 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20  .** interpreted 
13800 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68  as a boolean, wh
13810 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ich enables or d
13820 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c  isables the coll
13830 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d  ection of.** mem
13840 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
13850 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65  tatistics. ^(Whe
13860 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
13870 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
13880 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20  re.** disabled, 
13890 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  the following SQ
138a0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
138b0 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61  become non-opera
138c0 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c  tional:.**   <ul
138d0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  >.**   <li> [sql
138e0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
138f0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
13900 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
13910 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20  ghwater()].**   
13920 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f  <li> [sqlite3_so
13930 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
13940 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
13950 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34 28 29  lite3_status64()
13960 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a  ].**   </ul>)^.*
13970 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  * ^Memory alloca
13980 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
13990 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
139a0 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51  efault unless SQ
139b0 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
139c0 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
139d0 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54  _DEFAULT_MEMSTAT
139e0 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63  US]=0 in which c
139f0 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ase memory.** al
13a00 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
13a10 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
13a20 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20   by default..** 
13a30 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13a40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
13a50 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TCH]] <dt>SQLITE
13a60 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c  _CONFIG_SCRATCH<
13a70 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
13a80 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13a90 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 73  SCRATCH option s
13aa0 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
13ab0 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a  c memory buffer.
13ac0 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  ** that SQLite c
13ad0 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61 74  an use for scrat
13ae0 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68  ch memory.  ^(Th
13af0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
13b00 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51  guments.** to SQ
13b10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
13b20 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  TCH:  A pointer 
13b30 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
13b40 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  gned memory buff
13b50 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  er from which th
13b60 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  e scratch alloca
13b70 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a  tions will be.**
13b80 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65   drawn, the size
13b90 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68   of each scratch
13ba0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29   allocation (sz)
13bb0 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78  ,.** and the max
13bc0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73  imum number of s
13bd0 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
13be0 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65  ns (N).)^.** The
13bf0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
13c00 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65  must be a pointe
13c10 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61  r to an 8-byte a
13c20 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a  ligned buffer.**
13c30 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
13c40 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
13c50 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
13c60 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20  ll not use more 
13c70 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68  than one scratch
13c80 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72   buffers per thr
13c90 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ead..** ^SQLite 
13ca0 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65  will never reque
13cb0 73 74 20 61 20 73 63 72 61 74 63 68 20 62 75 66  st a scratch buf
13cc0 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65  fer that is more
13cd0 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73   than 6.** times
13ce0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
13cf0 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  ge size..** ^If 
13d00 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65  SQLite needs nee
13d10 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  ds additional.**
13d20 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
13d30 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
13d40 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
13d50 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13d60 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b  tion, then .** [
13d70 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13d80 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74  ] will be used t
13d90 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d  o obtain the mem
13da0 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a  ory needed.<p>.*
13db0 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c  * ^When the appl
13dc0 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73  ication provides
13dd0 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73   any amount of s
13de0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73  cratch memory us
13df0 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  ing.** SQLITE_CO
13e00 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51  NFIG_SCRATCH, SQ
13e10 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65  Lite avoids unne
13e20 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a  cessary large.**
13e30 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13e40 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e  |heap allocation
13e50 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20  s]..** This can 
13e60 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f  help [Robson pro
13e70 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72  of|prevent memor
13e80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
13e90 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65  lures] due to he
13ea0 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74  ap.** fragmentat
13eb0 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72  ion in low-memor
13ec0 79 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  y embedded syste
13ed0 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ms..** </dd>.**.
13ee0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13ef0 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c  IG_PAGECACHE]] <
13f00 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13f10 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a  _PAGECACHE</dt>.
13f20 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
13f30 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
13f40 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63  ACHE option spec
13f50 69 66 69 65 73 20 61 20 6d 65 6d 6f 72 79 20 70  ifies a memory p
13f60 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  ool.** that SQLi
13f70 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74  te can use for t
13f80 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
13f90 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20   cache with the 
13fa0 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20  default page.** 
13fb0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
13fc0 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20  tion.  .** This 
13fd0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13fe0 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70 20  tion is a no-op 
13ff0 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
14000 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a  n-define page.**
14010 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
14020 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20  ation is loaded 
14030 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
14040 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
14050 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65  ]..** ^There are
14060 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
14070 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
14080 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20 70  G_PAGECACHE: A p
14090 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62  ointer to.** 8-b
140a0 79 74 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  yte aligned memo
140b0 72 79 20 28 70 4d 65 6d 29 2c 20 74 68 65 20 73  ry (pMem), the s
140c0 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65  ize of each page
140d0 20 63 61 63 68 65 20 6c 69 6e 65 20 28 73 7a 29   cache line (sz)
140e0 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75 6d  ,.** and the num
140f0 62 65 72 20 6f 66 20 63 61 63 68 65 20 6c 69 6e  ber of cache lin
14100 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
14110 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
14120 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
14130 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
14140 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
14150 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
14160 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35  tween 512 and 65
14170 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65  536) plus some e
14180 78 74 72 61 20 62 79 74 65 73 20 66 6f 72 20 65  xtra bytes for e
14190 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64  ach.** page head
141a0 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72  er.  ^The number
141b0 20 6f 66 20 65 78 74 72 61 20 62 79 74 65 73 20   of extra bytes 
141c0 6e 65 65 64 65 64 20 62 79 20 74 68 65 20 70 61  needed by the pa
141d0 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e  ge header.** can
141e0 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
141f0 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  sing [SQLITE_CON
14200 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
14210 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61 72  ]..** ^It is har
14220 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f  mless, apart fro
14230 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d  m the wasted mem
14240 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ory,.** for the 
14250 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  sz parameter to 
14260 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 6e  be larger than n
14270 65 63 65 73 73 61 72 79 2e 20 20 54 68 65 20 70  ecessary.  The p
14280 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  Mem.** argument 
14290 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
142a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
142b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
142c0 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e   8-byte.** align
142d0 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f  ed block of memo
142e0 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  ry of at least s
142f0 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68 65 72  z*N bytes, other
14300 77 69 73 65 0a 2a 2a 20 73 75 62 73 65 71 75 65  wise.** subseque
14310 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  nt behavior is u
14320 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68  ndefined..** ^Wh
14330 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20 4e  en pMem is not N
14340 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ULL, SQLite will
14350 20 73 74 72 69 76 65 20 74 6f 20 75 73 65 20 74   strive to use t
14360 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64  he memory provid
14370 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66 79  ed.** to satisfy
14380 20 70 61 67 65 20 63 61 63 68 65 20 6e 65 65 64   page cache need
14390 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b 20  s, falling back 
143a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
143b0 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70 61  oc()] if.** a pa
143c0 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 69 73  ge cache line is
143d0 20 6c 61 72 67 65 72 20 74 68 61 6e 20 73 7a 20   larger than sz 
143e0 62 79 74 65 73 20 6f 72 20 69 66 20 61 6c 6c 20  bytes or if all 
143f0 6f 66 20 74 68 65 20 70 4d 65 6d 20 62 75 66 66  of the pMem buff
14400 65 72 0a 2a 2a 20 69 73 20 65 78 68 61 75 73 74  er.** is exhaust
14410 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d 20  ed..** ^If pMem 
14420 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73  is NULL and N is
14430 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
14440 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
14450 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73  nnection.** does
14460 20 61 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c 6b   an initial bulk
14470 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
14480 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
14490 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  y.** from [sqlit
144a0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75 66  e3_malloc()] suf
144b0 66 69 63 69 65 6e 74 20 66 6f 72 20 4e 20 63 61  ficient for N ca
144c0 63 68 65 20 6c 69 6e 65 73 20 69 66 20 4e 20 69  che lines if N i
144d0 73 20 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a 2a  s positive or.**
144e0 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79 74 65   of -1024*N byte
144f0 73 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69  s if N is negati
14500 76 65 2c 20 2e 20 5e 49 66 20 61 64 64 69 74 69  ve, . ^If additi
14510 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63  onal.** page cac
14520 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65  he memory is nee
14530 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ded beyond what 
14540 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
14550 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c  he initial.** al
14560 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 53  location, then S
14570 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73  QLite goes to [s
14580 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
14590 20 73 65 70 61 72 61 74 65 6c 79 20 66 6f 72 20   separately for 
145a0 65 61 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f 6e  each.** addition
145b0 61 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e 20 3c  al cache line. <
145c0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
145d0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
145e0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
145f0 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
14600 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
14610 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70  E_CONFIG_HEAP op
14620 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
14630 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
14640 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53  uffer .** that S
14650 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66  QLite will use f
14660 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
14670 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
14680 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a  ocation needs.**
14690 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72   beyond those pr
146a0 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53  ovided for by [S
146b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
146c0 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51  ATCH] and.** [SQ
146d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
146e0 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20  CACHE]..** ^The 
146f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
14700 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  AP option is onl
14710 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53  y available if S
14720 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
14730 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72  d.** with either
14740 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
14750 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c  MEMSYS3] or [SQL
14760 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
14770 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  S5] and returns.
14780 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
14790 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68  ] if invoked oth
147a0 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72  erwise..** ^Ther
147b0 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
147c0 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f  ments to SQLITE_
147d0 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20  CONFIG_HEAP:.** 
147e0 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  An 8-byte aligne
147f0 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  d pointer to the
14800 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20   memory,.** the 
14810 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
14820 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75  in the memory bu
14830 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69  ffer, and the mi
14840 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
14850 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68   size..** ^If th
14860 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
14870 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
14880 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ter) is NULL, th
14890 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74  en SQLite revert
148a0 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74  s.** to using it
148b0 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  s default memory
148c0 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20   allocator (the 
148d0 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
148e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c  implementation),
148f0 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20  .** undoing any 
14900 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e  prior invocation
14910 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   of [SQLITE_CONF
14920 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66  IG_MALLOC].  ^If
14930 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
14940 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
14950 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65  LL then the alte
14960 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a  rnative memory.*
14970 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65  * allocator is e
14980 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65  ngaged to handle
14990 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20   all of SQLites 
149a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
149b0 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20  n needs..** The 
149c0 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
149d0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
149e0 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  r) must be align
149f0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  ed to an 8-byte.
14a00 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73  ** boundary or s
14a10 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
14a20 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c  or of SQLite wil
14a30 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a  l be undefined..
14a40 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61  ** The minimum a
14a50 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69  llocation size i
14a60 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31  s capped at 2**1
14a70 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61  2. Reasonable va
14a80 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20  lues.** for the 
14a90 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
14aa0 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35  on size are 2**5
14ab0 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f   through 2**8.</
14ac0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14ad0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d  TE_CONFIG_MUTEX]
14ae0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14af0 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  FIG_MUTEX</dt>.*
14b00 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
14b10 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
14b20 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
14b30 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14b40 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f  which is a.** po
14b50 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
14b60 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
14b70 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
14b80 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
14b90 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73  * The argument s
14ba0 70 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61  pecifies alterna
14bb0 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
14bc0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f  utex routines to
14bd0 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70   be used.** in p
14be0 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78 20 72  lace the mutex r
14bf0 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
14c00 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53  to SQLite.)^  ^S
14c10 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
14c20 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
14c30 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
14c40 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
14c50 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65  ds] structure be
14c60 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f  fore the call to
14c70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
14c80 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20  fig()] returns. 
14c90 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
14ca0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
14cb0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
14cc0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
14cd0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
14ce0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
14cf0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
14d00 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
14d10 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
14d20 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
14d30 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
14d40 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
14d50 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
14d60 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14d70 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  _MUTEX configura
14d80 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
14d90 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
14da0 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
14db0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14dc0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d  ONFIG_GETMUTEX]]
14dd0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14de0 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
14df0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14e00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14e10 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b  MUTEX option tak
14e20 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14e30 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
14e40 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
14e50 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
14e60 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
14e70 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
14e80 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  re.  The.** [sql
14e90 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
14ea0 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
14eb0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
14ec0 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
14ed0 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74  fined mutex rout
14ee0 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
14ef0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
14f00 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
14f10 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
14f20 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
14f30 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
14f40 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
14f50 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
14f60 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
14f70 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
14f80 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
14f90 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c  ample.   ^If SQL
14fa0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
14fb0 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
14fc0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
14fd0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
14fe0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
14ff0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
15000 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
15010 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
15020 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
15030 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
15040 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
15050 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
15060 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
15070 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
15080 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
15090 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
150a0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
150b0 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
150c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
150d0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64  G_LOOKASIDE]] <d
150e0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
150f0 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
15100 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
15110 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
15120 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65  SIDE option take
15130 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20  s two arguments 
15140 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a  that determine.*
15150 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 73 69  * the default si
15160 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20  ze of lookaside 
15170 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b  memory on each [
15180 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15190 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ion]..** The fir
151a0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
151b0 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
151c0 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
151d0 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
151e0 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e   second is the n
151f0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
15200 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65  s allocated to e
15210 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
15220 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51  nection.)^  ^(SQ
15230 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
15240 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68  ASIDE.** sets th
15250 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e  e <i>default</i>
15260 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e   lookaside size.
15270 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43   The [SQLITE_DBC
15280 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
15290 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73  .** option to [s
152a0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
152b0 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20  ()] can be used 
152c0 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f  to change the lo
152d0 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69  okaside.** confi
152e0 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  guration on indi
152f0 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f  vidual connectio
15300 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ns.)^ </dd>.**.*
15310 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15320 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  G_PCACHE2]] <dt>
15330 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15340 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
15350 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
15360 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f  CONFIG_PCACHE2 o
15370 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
15380 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
15390 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69  ich is .** a poi
153a0 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69  nter to an [sqli
153b0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
153c0 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  ds2] object.  Th
153d0 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  is object specif
153e0 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72  ies.** the inter
153f0 66 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d  face to a custom
15400 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
15410 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a  ementation.)^.**
15420 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
15430 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
15440 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
15450 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f  hods2] object.</
15460 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15470 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
15480 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
15490 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
154a0 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
154b0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
154c0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
154d0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
154e0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
154f0 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
15500 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69  nter to an [sqli
15510 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
15520 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51  ds2] object.  SQ
15530 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a  Lite copies of.*
15540 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20 70 61  * the current pa
15550 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
15560 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61  ntation into tha
15570 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64  t object.)^ </dd
15580 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15590 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64  _CONFIG_LOG]] <d
155a0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
155b0 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOG</dt>.** <dd>
155c0 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   The SQLITE_CONF
155d0 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73  IG_LOG option is
155e0 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
155f0 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a  re the SQLite.**
15600 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c   global [error l
15610 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51  og]..** (^The SQ
15620 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
15630 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
15640 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f   arguments: a po
15650 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75  inter to a.** fu
15660 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61  nction with a ca
15670 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20  ll signature of 
15680 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e  void(*)(void*,in
15690 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  t,const char*), 
156a0 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65  .** and a pointe
156b0 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74  r to void. ^If t
156c0 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  he function poin
156d0 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ter is not NULL,
156e0 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65   it is.** invoke
156f0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  d by [sqlite3_lo
15700 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20  g()] to process 
15710 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65  each logging eve
15720 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
15730 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
15740 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73   is NULL, the [s
15750 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e  qlite3_log()] in
15760 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20  terface becomes 
15770 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65  a no-op..** ^The
15780 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68   void pointer th
15790 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64  at is the second
157a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c   argument to SQL
157b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69  ITE_CONFIG_LOG i
157c0 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f  s.** passed thro
157d0 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
157e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
157f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
15800 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
15810 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65  function wheneve
15820 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20  r that function 
15830 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68  is invoked.  ^Th
15840 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
15850 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67  er to.** the log
15860 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ger function is 
15870 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69  a copy of the fi
15880 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
15890 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
158a0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  ng.** [sqlite3_l
158b0 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69  og()] call and i
158c0 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65  s intended to be
158d0 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d   a [result code]
158e0 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e   or an.** [exten
158f0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
15900 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  .  ^The third pa
15910 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74  rameter passed t
15920 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a  o the logger is.
15930 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61  ** log message a
15940 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20  fter formatting 
15950 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  via [sqlite3_snp
15960 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65  rintf()]..** The
15970 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20   SQLite logging 
15980 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
15990 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20   reentrant; the 
159a0 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a  logger function.
159b0 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74  ** supplied by t
159c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
159d0 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61  ust not invoke a
159e0 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
159f0 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c  ace..** In a mul
15a00 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c  ti-threaded appl
15a10 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70  ication, the app
15a20 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
15a30 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
15a40 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65  ion must be thre
15a50 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  adsafe. </dd>.**
15a60 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15a70 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51  FIG_URI]] <dt>SQ
15a80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a  LITE_CONFIG_URI.
15a90 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c  ** <dd>^(The SQL
15aa0 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f  ITE_CONFIG_URI o
15ab0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
15ac0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
15ad0 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66   type int..** If
15ae0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
15af0 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
15b00 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64  globally enabled
15b10 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74  . If the paramet
15b20 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74  er is zero,.** t
15b30 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
15b40 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
15b50 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49  abled.)^ ^If URI
15b60 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
15b70 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64  bally.** enabled
15b80 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20  , all filenames 
15b90 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
15ba0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
15bb0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
15bc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
15bd0 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65  n16()] or.** spe
15be0 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f  cified as part o
15bf0 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61  f [ATTACH] comma
15c00 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  nds are interpre
15c10 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67  ted as URIs, reg
15c20 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68  ardless.** of wh
15c30 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
15c40 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
15c50 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  I] flag is set w
15c60 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
15c70 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
15c80 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74  s opened. ^If it
15c90 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
15ca0 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73  abled, filenames
15cb0 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74   are.** only int
15cc0 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
15cd0 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f   if the SQLITE_O
15ce0 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20  PEN_URI flag is 
15cf0 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  set when the.** 
15d00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15d10 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
15d20 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49  (By default, URI
15d30 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
15d40 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65  bally.** disable
15d50 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  d. The default v
15d60 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e  alue may be chan
15d70 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67  ged by compiling
15d80 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
15d90 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79  LITE_USE_URI] sy
15da0 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a  mbol defined.)^.
15db0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15dc0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
15dd0 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e  NDEX_SCAN]] <dt>
15de0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
15df0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
15e00 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  N.** <dd>^The SQ
15e10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
15e20 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
15e30 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15e40 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a  ingle integer.**
15e50 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
15e60 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
15e70 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f  s a boolean in o
15e80 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f  rder to enable o
15e90 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  r disable.** the
15ea0 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67   use of covering
15eb0 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c   indices for ful
15ec0 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e  l table scans in
15ed0 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d   the query optim
15ee0 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  izer..** ^The de
15ef0 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73  fault setting is
15f00 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62   determined.** b
15f10 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c  y the [SQLITE_AL
15f20 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  LOW_COVERING_IND
15f30 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65  EX_SCAN] compile
15f40 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72  -time option, or
15f50 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74   is "on".** if t
15f60 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  hat compile-time
15f70 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74   option is omitt
15f80 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69  ed..** The abili
15f90 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68  ty to disable th
15fa0 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
15fb0 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75  g indices for fu
15fc0 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a  ll table scans.*
15fd0 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d  * is because som
15fe0 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f  e incorrectly co
15ff0 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69  ded legacy appli
16000 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61  cations might ma
16010 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65  lfunction.** whe
16020 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  n the optimizati
16030 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20  on is enabled.  
16040 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62  Providing the ab
16050 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61  ility to.** disa
16060 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  ble the optimiza
16070 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20  tion allows the 
16080 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70  older, buggy app
16090 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f  lication code to
160a0 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74   work.** without
160b0 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74   change even wit
160c0 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73  h newer versions
160d0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
160e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
160f0 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c  G_PCACHE]] [[SQL
16100 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
16110 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  ACHE]].** <dt>SQ
16120 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
16130 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f  HE and SQLITE_CO
16140 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a  NFIG_GETPCACHE.*
16150 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74  * <dd> These opt
16160 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74  ions are obsolet
16170 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74  e and should not
16180 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20   be used by new 
16190 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72  code..** They ar
161a0 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62  e retained for b
161b0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
161c0 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e  bility but are n
161d0 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f  ow no-ops..** </
161e0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
161f0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
16200 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
16210 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a  _CONFIG_SQLLOG.*
16220 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
16230 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
16240 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73  ble if sqlite is
16250 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
16260 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
16270 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65  ABLE_SQLLOG] pre
16280 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
16290 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69   defined. The fi
162a0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rst argument sho
162b0 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e  uld.** be a poin
162c0 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  ter to a functio
162d0 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a  n of type void(*
162e0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
162f0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e  ,const char*, in
16300 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  t)..** The secon
16310 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74  d should be of t
16320 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65  ype (void*). The
16330 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
16340 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72  oked by the libr
16350 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20  ary.** in three 
16360 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73  separate circums
16370 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69  tances, identifi
16380 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20  ed by the value 
16390 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a  passed as the.**
163a0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
163b0 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  r. If the fourth
163c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c   parameter is 0,
163d0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
163e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
163f0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
16400 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68  econd argument h
16410 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65  as just been ope
16420 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61  ned. The third a
16430 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74  rgument.** point
16440 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f  s to a buffer co
16450 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d  ntaining the nam
16460 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61  e of the main da
16470 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20  tabase file. If 
16480 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
16490 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68  rameter is 1, th
164a0 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
164b0 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68  ment that the th
164c0 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ird parameter.**
164d0 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a   points to has j
164e0 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65  ust been execute
164f0 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f  d. Or, if the fo
16500 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
16510 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  s 2, then.** the
16520 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e   connection bein
16530 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  g passed as the 
16540 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16550 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64   is being closed
16560 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  . The.** third p
16570 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73  arameter is pass
16580 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20  ed NULL In this 
16590 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c  case.  An exampl
165a0 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a  e of using this.
165b0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
165c0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73   option can be s
165d0 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74  een in the "test
165e0 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63  _sqllog.c" sourc
165f0 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65  e file in.** the
16600 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74   canonical SQLit
16610 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f  e source tree.</
16620 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
16630 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
16640 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
16650 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
16660 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c  SIZE.** <dd>^SQL
16670 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
16680 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36  SIZE takes two 6
16690 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73  4-bit integer (s
166a0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61  qlite3_int64) va
166b0 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  lues.** that are
166c0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61   the default mma
166d0 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68  p size limit (th
166e0 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
166f0 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41  g for.** [PRAGMA
16700 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64   mmap_size]) and
16710 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c   the maximum all
16720 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c  owed mmap size l
16730 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  imit..** ^The de
16740 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61  fault setting ca
16750 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20  n be overridden 
16760 62 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65  by each database
16770 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e   connection usin
16780 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20  g.** either the 
16790 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
167a0 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62  e] command, or b
167b0 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  y using the.** [
167c0 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
167d0 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
167e0 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78  trol.  ^(The max
167f0 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61  imum allowed mma
16800 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62  p size.** will b
16810 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  e silently trunc
16820 61 74 65 64 20 69 66 20 6e 65 63 65 73 73 61 72  ated if necessar
16830 79 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65  y so that it doe
16840 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65  s not exceed the
16850 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
16860 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69   maximum mmap si
16870 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a  ze set by the.**
16880 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41   [SQLITE_MAX_MMA
16890 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d  P_SIZE] compile-
168a0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a  time option.)^.*
168b0 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 67  * ^If either arg
168c0 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70  ument to this op
168d0 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65  tion is negative
168e0 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 75  , then that argu
168f0 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67  ment is.** chang
16900 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c  ed to its compil
16910 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a  e-time default..
16920 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16930 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
16940 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  SIZE]].** <dt>SQ
16950 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
16960 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64  2_HEAPSIZE.** <d
16970 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
16980 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
16990 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  IZE option is on
169a0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
169b0 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
169c0 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77  piled for Window
169d0 73 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  s with the [SQLI
169e0 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d  TE_WIN32_MALLOC]
169f0 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
16a00 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e  acro.** defined.
16a10 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   ^SQLITE_CONFIG_
16a20 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74  WIN32_HEAPSIZE t
16a30 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e  akes a 32-bit un
16a40 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76  signed integer v
16a50 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65  alue.** that spe
16a60 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d  cifies the maxim
16a70 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63  um size of the c
16a80 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a  reated heap..**.
16a90 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
16aa0 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d  IG_PCACHE_HDRSZ]
16ab0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
16ac0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
16ad0 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  RSZ.** <dd>^The 
16ae0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
16af0 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f  ACHE_HDRSZ optio
16b00 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
16b10 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
16b20 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
16b30 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61   to an integer a
16b40 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74  nd writes into t
16b50 68 61 74 20 69 6e 74 65 67 65 72 20 74 68 65 20  hat integer the 
16b60 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a  number of extra.
16b70 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70 61 67  ** bytes per pag
16b80 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65  e required for e
16b90 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c  ach page in [SQL
16ba0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
16bb0 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d  ACHE]..** The am
16bc0 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70  ount of extra sp
16bd0 61 63 65 20 72 65 71 75 69 72 65 64 20 63 61 6e  ace required can
16be0 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e   change dependin
16bf0 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65  g on the compile
16c00 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61  r,.** target pla
16c10 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74  tform, and SQLit
16c20 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  e version..**.**
16c30 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16c40 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e  _PMASZ]].** <dt>
16c50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
16c60 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  ASZ.** <dd>^The 
16c70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
16c80 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  ASZ option takes
16c90 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
16ca0 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
16cb0 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  an unsigned inte
16cc0 67 65 72 20 61 6e 64 20 73 65 74 73 20 74 68 65  ger and sets the
16cd0 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69   "Minimum PMA Si
16ce0 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74  ze" for the mult
16cf0 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72  ithreaded.** sor
16d00 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65  ter to that inte
16d10 67 65 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ger.  The defaul
16d20 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69  t minimum PMA Si
16d30 7a 65 20 69 73 20 73 65 74 20 62 79 20 74 68 65  ze is set by the
16d40 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54  .** [SQLITE_SORT
16d50 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c  ER_PMASZ] compil
16d60 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20  e-time option.  
16d70 4e 65 77 20 74 68 72 65 61 64 73 20 61 72 65 20  New threads are 
16d80 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68  launched.** to h
16d90 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70  elp with sort op
16da0 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75  erations when mu
16db0 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f 72 74  ltithreaded sort
16dc0 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65  ing.** is enable
16dd0 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52  d (using the [PR
16de0 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f  AGMA threads] co
16df0 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61  mmand) and the a
16e00 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74  mount of content
16e10 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64  .** to be sorted
16e20 20 65 78 63 65 65 64 73 20 74 68 65 20 70 61 67   exceeds the pag
16e30 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65  e size times the
16e40 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a   minimum of the.
16e50 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65  ** [PRAGMA cache
16e60 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61  _size] setting a
16e70 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a  nd this value..*
16e80 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16e90 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  NFIG_STMTJRNL_SP
16ea0 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  ILL]].** <dt>SQL
16eb0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
16ec0 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64  RNL_SPILL.** <dd
16ed0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
16ee0 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  FIG_STMTJRNL_SPI
16ef0 4c 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  LL option takes 
16f00 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
16f10 65 72 20 77 68 69 63 68 0a 2a 2a 20 62 65 63 6f  er which.** beco
16f20 6d 65 73 20 74 68 65 20 5b 73 74 61 74 65 6d 65  mes the [stateme
16f30 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69 6c  nt journal] spil
16f40 6c 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65 73 68  l-to-disk thresh
16f50 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74 65  old.  .** [State
16f60 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20 61  ment journals] a
16f70 72 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72  re held in memor
16f80 79 20 75 6e 74 69 6c 20 74 68 65 69 72 20 73 69  y until their si
16f90 7a 65 20 28 69 6e 20 62 79 74 65 73 29 0a 2a 2a  ze (in bytes).**
16fa0 20 65 78 63 65 65 64 73 20 74 68 69 73 20 74 68   exceeds this th
16fb0 72 65 73 68 6f 6c 64 2c 20 61 74 20 77 68 69 63  reshold, at whic
16fc0 68 20 70 6f 69 6e 74 20 74 68 65 79 20 61 72 65  h point they are
16fd0 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
16fe0 2e 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65 20 74  ..** Or if the t
16ff0 68 72 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c 20  hreshold is -1, 
17000 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61  statement journa
17010 6c 73 20 61 72 65 20 61 6c 77 61 79 73 20 68 65  ls are always he
17020 6c 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65 6c  ld.** exclusivel
17030 79 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  y in memory..** 
17040 53 69 6e 63 65 20 6d 61 6e 79 20 73 74 61 74 65  Since many state
17050 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e 65  ment journals ne
17060 76 65 72 20 62 65 63 6f 6d 65 20 6c 61 72 67 65  ver become large
17070 2c 20 73 65 74 74 69 6e 67 20 74 68 65 20 73 70  , setting the sp
17080 69 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c 64  ill.** threshold
17090 20 74 6f 20 61 20 76 61 6c 75 65 20 73 75 63 68   to a value such
170a0 20 61 73 20 36 34 4b 69 42 20 63 61 6e 20 67 72   as 64KiB can gr
170b0 65 61 74 6c 79 20 72 65 64 75 63 65 20 74 68 65  eatly reduce the
170c0 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f   amount of.** I/
170d0 4f 20 72 65 71 75 69 72 65 64 20 74 6f 20 73 75  O required to su
170e0 70 70 6f 72 74 20 73 74 61 74 65 6d 65 6e 74 20  pport statement 
170f0 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  rollback..** The
17100 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66   default value f
17110 6f 72 20 74 68 69 73 20 73 65 74 74 69 6e 67 20  or this setting 
17120 69 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  is controlled by
17130 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
17140 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20  STMTJRNL_SPILL] 
17150 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
17160 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  ion..** </dl>.*/
17170 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17180 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
17190 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
171a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
171b0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
171c0 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
171d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
171e0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
171f0 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
17200 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17210 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
17220 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
17230 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
17240 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
17250 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
17260 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
17270 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
17280 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
17290 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
172a0 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
172b0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
172c0 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
172d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
172e0 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
172f0 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
17300 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
17310 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17320 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
17330 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
17340 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
17350 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17360 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
17370 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
17380 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
17390 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
173a0 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
173b0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
173c0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
173d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
173e0 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
173f0 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
17400 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
17410 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
17420 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
17430 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
17440 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
17450 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
17460 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
17470 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
17480 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
17490 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
174a0 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
174b0 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
174c0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
174d0 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
174e0 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
174f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17500 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
17510 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
17520 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
17530 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
17540 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
17550 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
17560 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
17570 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
17580 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
17590 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
175a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
175b0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
175c0 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
175d0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
175e0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
175f0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
17600 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
17610 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
17620 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17630 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
17640 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
17650 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
17660 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
17670 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20  MAP_SIZE    22  
17680 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
17690 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
176a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
176b0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
176c0 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20  EAPSIZE      23 
176d0 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
176e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
176f0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
17700 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f  RSZ        24  /
17710 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64  * int *psz */.#d
17720 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17730 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20  FIG_PMASZ       
17740 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75          25  /* u
17750 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d  nsigned int szPm
17760 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  a */.#define SQL
17770 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
17780 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32  RNL_SPILL      2
17790 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20  6  /* int nByte 
177a0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
177b0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
177c0 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
177d0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
177e0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
177f0 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
17800 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
17810 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
17820 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
17830 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
17840 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
17850 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
17860 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
17870 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
17880 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
17890 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
178a0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
178b0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
178c0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
178d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
178e0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
178f0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
17900 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
17910 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
17920 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
17930 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
17940 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
17950 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
17960 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
17970 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
17980 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
17990 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
179a0 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
179b0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
179c0 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
179d0 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
179e0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
179f0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
17a00 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
17a10 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17a20 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
17a30 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
17a40 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
17a50 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
17a60 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
17a70 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
17a80 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
17a90 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
17aa0 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
17ab0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17ac0 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
17ad0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
17ae0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
17af0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
17b00 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
17b10 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  ** pointer to a 
17b20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f  memory buffer to
17b30 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69   use for lookasi
17b40 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54  de memory..** ^T
17b50 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
17b60 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49  t after the SQLI
17b70 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
17b80 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61  ASIDE verb.** ma
17b90 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69  y be NULL in whi
17ba0 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77  ch case SQLite w
17bb0 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  ill allocate the
17bc0 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  .** lookaside bu
17bd0 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e  ffer itself usin
17be0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  g [sqlite3_mallo
17bf0 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e  c()]. ^The secon
17c00 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
17c10 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
17c20 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
17c30 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74  er slot.  ^The t
17c40 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
17c50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
17c60 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69  * slots.  The si
17c70 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
17c80 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
17c90 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67  gument must be g
17ca0 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f  reater than.** o
17cb0 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70  r equal to the p
17cc0 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65  roduct of the se
17cd0 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61  cond and third a
17ce0 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62  rguments.  The b
17cf0 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65  uffer.** must be
17d00 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
17d10 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20  -byte boundary. 
17d20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
17d30 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53  argument to.** S
17d40 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
17d50 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20  OOKASIDE is not 
17d60 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c  a multiple of 8,
17d70 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c   it is internall
17d80 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77  y.** rounded dow
17d90 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d  n to the next sm
17da0 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  aller multiple o
17db0 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b  f 8.  ^(The look
17dc0 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  aside memory.** 
17dd0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
17de0 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
17df0 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79  nection can only
17e00 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e   be changed when
17e10 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74   that.** connect
17e20 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65  ion is not curre
17e30 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61  ntly using looka
17e40 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20  side memory, or 
17e50 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a  in other words.*
17e60 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72  * when the "curr
17e70 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72  ent value" retur
17e80 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
17e90 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c  e3_db_status](D,
17ea0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
17eb0 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69  OOKASIDE],...) i
17ec0 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61  s zero..** Any a
17ed0 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65  ttempt to change
17ee0 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
17ef0 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74  emory configurat
17f00 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69  ion when lookasi
17f10 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20  de.** memory is 
17f20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68  in use leaves th
17f30 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
17f40 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65  unchanged and re
17f50 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  turns .** [SQLIT
17f60 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a  E_BUSY].)^</dd>.
17f70 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
17f80 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
17f90 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _FKEY</dt>.** <d
17fa0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
17fb0 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
17fc0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
17fd0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a   enforcement of.
17fe0 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
17ff0 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54  constraints].  T
18000 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
18010 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
18020 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
18030 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
18040 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
18050 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
18060 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
18070 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  t,.** positive t
18080 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f  o enable FK enfo
18090 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74  rcement or negat
180a0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20  ive to leave FK 
180b0 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75  enforcement.** u
180c0 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73  nchanged.  The s
180d0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
180e0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
180f0 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
18100 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
18110 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
18120 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46  dicate whether F
18130 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73  K enforcement is
18140 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f   off or on.** fo
18150 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
18160 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
18170 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
18180 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
18190 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
181a0 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d   the FK enforcem
181b0 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ent setting is n
181c0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
181d0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
181e0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
181f0 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
18200 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
18210 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
18220 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
18230 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20  disable [CREATE 
18240 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
18250 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  rs]..** There sh
18260 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
18270 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
18280 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
18290 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
182a0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
182b0 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67   to disable trig
182c0 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  gers,.** positiv
182d0 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67  e to enable trig
182e0 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65  gers or negative
182f0 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
18300 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e  tting unchanged.
18310 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
18320 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
18330 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
18340 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
18350 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
18360 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
18370 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73  whether triggers
18380 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72   are disabled or
18390 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
183a0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
183b0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
183c0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
183d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
183e0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
183f0 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69  he trigger setti
18400 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
18410 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
18420 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
18430 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
18440 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f  FTS3_TOKENIZER</
18450 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
18460 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
18470 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
18480 73 61 62 6c 65 20 74 68 65 20 74 77 6f 2d 61 72  sable the two-ar
18490 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 69 6f  gument.** versio
184a0 6e 20 6f 66 20 74 68 65 20 5b 66 74 73 33 5f 74  n of the [fts3_t
184b0 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75 6e 63  okenizer()] func
184c0 74 69 6f 6e 20 77 68 69 63 68 20 69 73 20 70 61  tion which is pa
184d0 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 46 54  rt of the.** [FT
184e0 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20 73 65  S3] full-text se
184f0 61 72 63 68 20 65 6e 67 69 6e 65 20 65 78 74 65  arch engine exte
18500 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20  nsion..** There 
18510 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
18520 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
18530 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
18540 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
18550 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
18560 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 66 74   0 to disable ft
18570 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f  s3_tokenizer() o
18580 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  r.** positive to
18590 20 65 6e 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b   enable fts3_tok
185a0 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65 67 61  enizer() or nega
185b0 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
185c0 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63  e setting.** unc
185d0 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
185e0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
185f0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
18600 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
18610 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
18620 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
18630 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 66  dicate whether f
18640 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 69 73  ts3_tokenizer is
18650 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
18660 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
18670 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
18680 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18690 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
186a0 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
186b0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e  which case the n
186c0 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  ew setting is no
186d0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
186e0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
186f0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
18700 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54  _ENABLE_LOAD_EXT
18710 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  ENSION</dt>.** <
18720 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
18730 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
18740 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
18750 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  e [sqlite3_load_
18760 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20  extension()].** 
18770 69 6e 74 65 72 66 61 63 65 20 69 6e 64 65 70 65  interface indepe
18780 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68 65 20 5b  ndently of the [
18790 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
187a0 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a  ] SQL function..
187b0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
187c0 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
187d0 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20 65 6e 61  nsion()] API ena
187e0 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
187f0 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43 2d 41   both the.** C-A
18800 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64  PI [sqlite3_load
18810 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 61 6e  _extension()] an
18820 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  d the SQL functi
18830 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69  on [load_extensi
18840 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  on()]..** There 
18850 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
18860 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
18870 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  ts..** When the 
18880 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
18890 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  o this interface
188a0 20 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e 6c 79   is 1, then only
188b0 20 74 68 65 20 43 2d 41 50 49 20 69 73 0a 2a 2a   the C-API is.**
188c0 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 74 68 65   enabled and the
188d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
188e0 6d 61 69 6e 73 20 64 69 73 61 62 6c 65 64 2e 20  mains disabled. 
188f0 20 49 66 20 74 68 65 20 66 69 72 73 74 20 61 72   If the first ar
18900 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 69  gument to.** thi
18910 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 30  s interface is 0
18920 2c 20 74 68 65 6e 20 62 6f 74 68 20 74 68 65 20  , then both the 
18930 43 2d 41 50 49 20 61 6e 64 20 74 68 65 20 53 51  C-API and the SQ
18940 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 64  L function are d
18950 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66 20 74  isabled..** If t
18960 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18970 74 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 6e 6f  t is -1, then no
18980 20 63 68 61 6e 67 65 73 20 61 72 65 20 6d 61 64   changes are mad
18990 65 20 74 6f 20 73 74 61 74 65 20 6f 66 20 65 69  e to state of ei
189a0 74 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d 41 50  ther the.** C-AP
189b0 49 20 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e  I or the SQL fun
189c0 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73 65  ction..** The se
189d0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
189e0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
189f0 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
18a00 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
18a10 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
18a20 69 63 61 74 65 20 77 68 65 74 68 65 72 20 5b 73  icate whether [s
18a30 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
18a40 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61  nsion()] interfa
18a50 63 65 0a 2a 2a 20 69 73 20 64 69 73 61 62 6c 65  ce.** is disable
18a60 64 20 6f 72 20 65 6e 61 62 6c 65 64 20 66 6f 6c  d or enabled fol
18a70 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
18a80 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
18a90 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a 20 62  rameter may.** b
18aa0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
18ab0 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  , in which case 
18ac0 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67 20  the new setting 
18ad0 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
18ae0 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  back..** </dd>.*
18af0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
18b00 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e  DBCONFIG_MAINDBN
18b10 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  AME</dt>.** <dd>
18b20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
18b30 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
18b40 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
18b50 22 6d 61 69 6e 22 20 64 61 74 61 62 61 73 65 0a  "main" database.
18b60 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e 54 68 65  ** schema.  ^The
18b70 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e 74 20 69   sole argument i
18b80 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
18b90 20 63 6f 6e 73 74 61 6e 74 20 55 54 46 38 20 73   constant UTF8 s
18ba0 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63 68 20 77  tring.** which w
18bb0 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 6e  ill become the n
18bc0 65 77 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 69  ew schema name i
18bd0 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d 61 69 6e  n place of "main
18be0 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 64  ".  ^SQLite.** d
18bf0 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20 61 20 63  oes not make a c
18c00 6f 70 79 20 6f 66 20 74 68 65 20 6e 65 77 20 6d  opy of the new m
18c10 61 69 6e 20 73 63 68 65 6d 61 20 6e 61 6d 65 20  ain schema name 
18c20 73 74 72 69 6e 67 2c 20 73 6f 20 74 68 65 20 61  string, so the a
18c30 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
18c40 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  st ensure that t
18c50 68 65 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  he argument pass
18c60 65 64 20 69 6e 74 6f 20 74 68 69 73 20 44 42 43  ed into this DBC
18c70 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20 69 73 20  ONFIG option is 
18c80 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 75 6e 74  unchanged.** unt
18c90 69 6c 20 61 66 74 65 72 20 74 68 65 20 64 61 74  il after the dat
18ca0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18cb0 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64   closes..** </dd
18cc0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
18cd0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43  TE_DBCONFIG_NO_C
18ce0 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74  KPT_ON_CLOSE</dt
18cf0 3e 0a 2a 2a 20 3c 64 64 3e 20 55 73 75 61 6c 6c  >.** <dd> Usuall
18d00 79 2c 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  y, when a databa
18d10 73 65 20 69 6e 20 77 61 6c 20 6d 6f 64 65 20 69  se in wal mode i
18d20 73 20 63 6c 6f 73 65 64 20 6f 72 20 64 65 74 61  s closed or deta
18d30 63 68 65 64 20 66 72 6f 6d 20 61 20 0a 2a 2a 20  ched from a .** 
18d40 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 2c  database handle,
18d50 20 53 51 4c 69 74 65 20 63 68 65 63 6b 73 20 69   SQLite checks i
18d60 66 20 74 68 69 73 20 77 69 6c 6c 20 6d 65 61 6e  f this will mean
18d70 20 74 68 61 74 20 74 68 65 72 65 20 61 72 65 20   that there are 
18d80 6e 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65  now no .** conne
18d90 63 74 69 6f 6e 73 20 61 74 20 61 6c 6c 20 74 6f  ctions at all to
18da0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 49   the database. I
18db0 66 20 73 6f 2c 20 69 74 20 70 65 72 66 6f 72 6d  f so, it perform
18dc0 73 20 61 20 63 68 65 63 6b 70 6f 69 6e 74 20 0a  s a checkpoint .
18dd0 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 62 65 66  ** operation bef
18de0 6f 72 65 20 63 6c 6f 73 69 6e 67 20 74 68 65 20  ore closing the 
18df0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68 69 73  connection. This
18e00 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65 20 75   option may be u
18e10 73 65 64 20 74 6f 0a 2a 2a 20 6f 76 65 72 72 69  sed to.** overri
18e20 64 65 20 74 68 69 73 20 62 65 68 61 76 69 6f 75  de this behaviou
18e30 72 2e 20 54 68 65 20 66 69 72 73 74 20 70 61 72  r. The first par
18e40 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f  ameter passed to
18e50 20 74 68 69 73 20 6f 70 65 72 61 74 69 6f 6e 0a   this operation.
18e60 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ** is an integer
18e70 20 2d 20 6e 6f 6e 2d 7a 65 72 6f 20 74 6f 20 64   - non-zero to d
18e80 69 73 61 62 6c 65 20 63 68 65 63 6b 70 6f 69 6e  isable checkpoin
18e90 74 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20  ts-on-close, or 
18ea0 7a 65 72 6f 20 28 74 68 65 0a 2a 2a 20 64 65 66  zero (the.** def
18eb0 61 75 6c 74 29 20 74 6f 20 65 6e 61 62 6c 65 20  ault) to enable 
18ec0 74 68 65 6d 2e 20 54 68 65 20 73 65 63 6f 6e 64  them. The second
18ed0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
18ee0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
18ef0 74 65 67 65 72 0a 2a 2a 20 69 6e 74 6f 20 77 68  teger.** into wh
18f00 69 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 30  ich is written 0
18f10 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
18f20 65 20 77 68 65 74 68 65 72 20 63 68 65 63 6b 70  e whether checkp
18f30 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a  oints-on-close.*
18f40 2a 20 68 61 76 65 20 62 65 65 6e 20 64 69 73 61  * have been disa
18f50 62 6c 65 64 20 2d 20 30 20 69 66 20 74 68 65 79  bled - 0 if they
18f60 20 61 72 65 20 6e 6f 74 20 64 69 73 61 62 6c 65   are not disable
18f70 64 2c 20 31 20 69 66 20 74 68 65 79 20 61 72 65  d, 1 if they are
18f80 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
18f90 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
18fa0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47  NFIG_ENABLE_QPSG
18fb0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 28 54  </dt>.** <dd>^(T
18fc0 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
18fd0 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 6f  IG_ENABLE_QPSG o
18fe0 70 74 69 6f 6e 20 61 63 74 69 76 61 74 65 73 20  ption activates 
18ff0 6f 72 20 64 65 61 63 74 69 76 61 74 65 73 0a 2a  or deactivates.*
19000 2a 20 74 68 65 20 5b 71 75 65 72 79 20 70 6c 61  * the [query pla
19010 6e 6e 65 72 20 73 74 61 62 69 6c 69 74 79 20 67  nner stability g
19020 75 61 72 61 6e 74 65 65 5d 20 28 51 50 53 47 29  uarantee] (QPSG)
19030 2e 20 20 57 68 65 6e 20 74 68 65 20 51 50 53 47  .  When the QPSG
19040 20 69 73 20 61 63 74 69 76 65 2c 0a 2a 2a 20 61   is active,.** a
19050 20 73 69 6e 67 6c 65 20 53 51 4c 20 71 75 65 72   single SQL quer
19060 79 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  y statement will
19070 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 65 20   always use the 
19080 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 72  same algorithm r
19090 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20  egardless.** of 
190a0 76 61 6c 75 65 73 20 6f 66 20 5b 62 6f 75 6e 64  values of [bound
190b0 20 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 20   parameters].)^ 
190c0 54 68 65 20 51 50 53 47 20 64 69 73 61 62 6c 65  The QPSG disable
190d0 73 20 73 6f 6d 65 20 71 75 65 72 79 20 6f 70 74  s some query opt
190e0 69 6d 69 7a 61 74 69 6f 6e 73 0a 2a 2a 20 74 68  imizations.** th
190f0 61 74 20 6c 6f 6f 6b 20 61 74 20 74 68 65 20 76  at look at the v
19100 61 6c 75 65 73 20 6f 66 20 62 6f 75 6e 64 20 70  alues of bound p
19110 61 72 61 6d 65 74 65 72 73 2c 20 77 68 69 63 68  arameters, which
19120 20 63 61 6e 20 6d 61 6b 65 20 73 6f 6d 65 20 71   can make some q
19130 75 65 72 69 65 73 0a 2a 2a 20 73 6c 6f 77 65 72  ueries.** slower
19140 2e 20 20 42 75 74 20 74 68 65 20 51 50 53 47 20  .  But the QPSG 
19150 68 61 73 20 74 68 65 20 61 64 76 61 6e 74 61 67  has the advantag
19160 65 20 6f 66 20 6d 6f 72 65 20 70 72 65 64 69 63  e of more predic
19170 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 20  table behavior. 
19180 20 57 69 74 68 0a 2a 2a 20 74 68 65 20 51 50 53   With.** the QPS
19190 47 20 61 63 74 69 76 65 2c 20 53 51 4c 69 74 65  G active, SQLite
191a0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 75 73 65   will always use
191b0 20 74 68 65 20 73 61 6d 65 20 71 75 65 72 79 20   the same query 
191c0 70 6c 61 6e 20 69 6e 20 74 68 65 20 66 69 65 6c  plan in the fiel
191d0 64 20 61 73 0a 2a 2a 20 77 61 73 20 75 73 65 64  d as.** was used
191e0 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
191f0 69 6e 20 74 68 65 20 6c 61 62 2e 0a 2a 2a 20 3c  in the lab..** <
19200 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
19210 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
19220 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e  TE_DBCONFIG_MAIN
19230 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  DBNAME          
19240 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20    1000 /* const 
19250 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  char* */.#define
19260 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
19270 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20  _LOOKASIDE      
19280 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76         1001 /* v
19290 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
192a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
192b0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
192c0 4b 45 59 20 20 20 20 20 20 20 20 20 20 20 31 30  KEY           10
192d0 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  02 /* int int* *
192e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
192f0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
19300 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
19310 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1003 /* int int*
19320 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19330 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
19340 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45  LE_FTS3_TOKENIZE
19350 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e  R 1004 /* int in
19360 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
19370 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
19380 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53  ABLE_LOAD_EXTENS
19390 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20  ION 1005 /* int 
193a0 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
193b0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
193c0 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45  NO_CKPT_ON_CLOSE
193d0 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e        1006 /* in
193e0 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
193f0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
19400 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 20 20  G_ENABLE_QPSG   
19410 20 20 20 20 20 20 20 20 31 30 30 37 20 2f 2a 20          1007 /* 
19420 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a  int int* */.../*
19430 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
19440 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
19450 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
19460 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Codes.** METHOD:
19470 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
19480 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
19490 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
194a0 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
194b0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
194c0 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
194d0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
194e0 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
194f0 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
19500 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
19510 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
19520 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
19530 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
19540 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
19550 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
19560 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
19570 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
19580 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19590 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
195a0 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  wid.** METHOD: s
195b0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61  qlite3.**.** ^Ea
195c0 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
195d0 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
195e0 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
195f0 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
19600 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
19610 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
19620 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
19630 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
19640 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
19650 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
19660 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
19670 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
19680 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
19690 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
196a0 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
196b0 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
196c0 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
196d0 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
196e0 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
196f0 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
19700 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
19710 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
19720 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
19730 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
19740 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
19750 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
19760 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
19770 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
19780 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
19790 63 65 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72  ce usually retur
197a0 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
197b0 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  f.** the most re
197c0 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20  cent successful 
197d0 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20  [INSERT] into a 
197e0 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b  rowid table or [
197f0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
19800 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f  * on database co
19810 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73  nnection D. ^Ins
19820 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f  erts into [WITHO
19830 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
19840 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f   are not.** reco
19850 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63  rded. ^If no suc
19860 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
19870 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62  s into rowid tab
19880 6c 65 73 20 68 61 76 65 20 65 76 65 72 20 6f 63  les have ever oc
19890 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68  curred .** on th
198a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
198b0 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71  ction D, then sq
198c0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
198d0 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72  t_rowid(D) retur
198e0 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a  ns .** zero..**.
198f0 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73 20 62 65  ** As well as be
19900 69 6e 67 20 73 65 74 20 61 75 74 6f 6d 61 74 69  ing set automati
19910 63 61 6c 6c 79 20 61 73 20 72 6f 77 73 20 61 72  cally as rows ar
19920 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20  e inserted into 
19930 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c  database.** tabl
19940 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  es, the value re
19950 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66  turned by this f
19960 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 73  unction may be s
19970 65 74 20 65 78 70 6c 69 63 69 74 6c 79 20 62 79  et explicitly by
19980 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
19990 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
199a0 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65  id()].**.** Some
199b0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
199c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
199d0 61 79 20 49 4e 53 45 52 54 20 72 6f 77 73 20 69  ay INSERT rows i
199e0 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73  nto rowid tables
199f0 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63   as.** part of c
19a00 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74 72 61 6e  ommitting a tran
19a10 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f  saction (e.g. to
19a20 20 66 6c 75 73 68 20 64 61 74 61 20 61 63 63 75   flush data accu
19a30 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72  mulated in memor
19a40 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49  y.** to disk). I
19a50 6e 20 74 68 69 73 20 63 61 73 65 20 73 75 62 73  n this case subs
19a60 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
19a70 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
19a80 74 75 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a  turn the rowid.*
19a90 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
19aa0 68 20 74 68 65 73 65 20 69 6e 74 65 72 6e 61 6c  h these internal
19ab0 20 49 4e 53 45 52 54 20 6f 70 65 72 61 74 69 6f   INSERT operatio
19ac0 6e 73 2c 20 77 68 69 63 68 20 6c 65 61 64 73 20  ns, which leads 
19ad0 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69  to .** unintuiti
19ae0 76 65 20 72 65 73 75 6c 74 73 2e 20 56 69 72 74  ve results. Virt
19af0 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
19b00 65 6e 74 61 74 69 6f 6e 73 20 74 68 61 74 20 64  entations that d
19b10 6f 20 77 72 69 74 65 20 74 6f 20 72 6f 77 69 64  o write to rowid
19b20 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e 20 74 68  .** tables in th
19b30 69 73 20 77 61 79 20 63 61 6e 20 61 76 6f 69 64  is way can avoid
19b40 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 62 79   this problem by
19b50 20 72 65 73 74 6f 72 69 6e 67 20 74 68 65 20 6f   restoring the o
19b60 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69  riginal .** rowi
19b70 64 20 76 61 6c 75 65 20 75 73 69 6e 67 20 5b 73  d value using [s
19b80 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f  qlite3_set_last_
19b90 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
19ba0 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
19bb0 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20   .** control to 
19bc0 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20  the user..**.** 
19bd0 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
19be0 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
19bf0 20 74 72 69 67 67 65 72 20 74 68 65 6e 20 74 68   trigger then th
19c00 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
19c10 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 5b  .** return the [
19c20 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
19c30 73 65 72 74 65 64 20 72 6f 77 20 61 73 20 6c 6f  serted row as lo
19c40 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
19c50 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67  r is .** running
19c60 2e 20 4f 6e 63 65 20 74 68 65 20 74 72 69 67 67  . Once the trigg
19c70 65 72 20 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c  er program ends,
19c80 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
19c90 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20  ned .** by this 
19ca0 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
19cb0 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62  to what it was b
19cc0 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
19cd0 72 20 77 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a  r was fired.)^.*
19ce0 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
19cf0 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
19d00 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
19d10 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
19d20 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
19d30 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
19d40 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
19d50 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
19d60 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
19d70 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
19d80 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
19d90 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
19da0 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
19db0 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
19dc0 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
19dd0 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
19de0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
19df0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
19e00 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
19e10 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
19e20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
19e30 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
19e40 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
19e50 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
19e60 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
19e70 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
19e80 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
19e90 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
19ea0 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
19eb0 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
19ec0 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
19ed0 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
19ee0 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
19ef0 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
19f00 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
19f10 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
19f20 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
19f30 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
19f40 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
19f50 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
19f60 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
19f70 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
19f80 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
19f90 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
19fa0 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
19fb0 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
19fc0 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
19fd0 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
19fe0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19ff0 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
1a000 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
1a010 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
1a020 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
1a030 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
1a040 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
1a050 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
1a060 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
1a070 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
1a080 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
1a090 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
1a0a0 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
1a0b0 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
1a0c0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
1a0d0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1a0e0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
1a0f0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
1a100 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
1a110 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
1a120 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
1a130 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
1a140 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
1a150 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74  rowid]..*/.sqlit
1a160 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1a170 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1a180 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
1a190 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1a1a0 65 74 20 74 68 65 20 4c 61 73 74 20 49 6e 73 65  et the Last Inse
1a1b0 72 74 20 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a  rt Rowid value..
1a1c0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1a1d0 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
1a1e0 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
1a1f0 73 65 72 74 5f 72 6f 77 69 64 28 44 2c 20 52 29  sert_rowid(D, R)
1a200 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74   method allows t
1a210 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
1a220 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20 76 61 6c  o.** set the val
1a230 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 63  ue returned by c
1a240 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c  alling sqlite3_l
1a250 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1a260 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74  (D) to R .** wit
1a270 68 6f 75 74 20 69 6e 73 65 72 74 69 6e 67 20 61  hout inserting a
1a280 20 72 6f 77 20 69 6e 74 6f 20 74 68 65 20 64 61   row into the da
1a290 74 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20  tabase..*/.void 
1a2a0 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74  sqlite3_set_last
1a2b0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
1a2c0 6c 69 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69  lite3*,sqlite3_i
1a2d0 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt64);../*.** CA
1a2e0 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
1a2f0 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
1a300 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54   Modified.** MET
1a310 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1a320 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1a330 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
1a340 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64  mber of rows mod
1a350 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20  ified, inserted 
1a360 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79  or.** deleted by
1a370 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1a380 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
1a390 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1a3a0 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
1a3b0 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  nt on the databa
1a3c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70  se connection sp
1a3d0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
1a3e0 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  nly parameter..*
1a3f0 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  * ^Executing any
1a400 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
1a410 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
1a420 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65  s not modify the
1a430 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
1a440 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
1a450 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  ion..**.** ^Only
1a460 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69   changes made di
1a470 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e  rectly by the IN
1a480 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
1a490 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
1a4a0 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
1a4b0 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63  ed - auxiliary c
1a4c0 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
1a4d0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
1a4e0 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a   | triggers], .*
1a4f0 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  * [foreign key a
1a500 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c  ctions] or [REPL
1a510 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20  ACE] constraint 
1a520 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e  resolution are n
1a530 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a  ot counted..** .
1a540 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20  ** Changes to a 
1a550 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e  view that are in
1a560 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a  tercepted by .**
1a570 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
1a580 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f  gger | INSTEAD O
1a590 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20  F triggers] are 
1a5a0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68  not counted. ^Th
1a5b0 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75  e value .** retu
1a5c0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1a5d0 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69  changes() immedi
1a5e0 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49  ately after an I
1a5f0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
1a600 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74   .** DELETE stat
1a610 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76  ement run on a v
1a620 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65  iew is always ze
1a630 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73  ro. Only changes
1a640 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a   made to real .*
1a650 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75  * tables are cou
1a660 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e  nted..**.** Thin
1a670 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70  gs are more comp
1a680 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73  licated if the s
1a690 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1a6a0 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
1a6b0 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61  executed while a
1a6c0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1a6d0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69   is running. Thi
1a6e0 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20  s may happen if 
1a6f0 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  the.** program u
1a700 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73  ses the [changes
1a710 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1a720 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68  , or if some oth
1a730 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  er callback.** f
1a740 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  unction invokes 
1a750 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1a760 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65  ) directly. Esse
1a770 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20  ntially:.** .** 
1a780 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  <ul>.**   <li> ^
1a790 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67  (Before entering
1a7a0 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
1a7b0 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  am the value ret
1a7c0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  urned by.**     
1a7d0 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67     sqlite3_chang
1a7e0 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
1a7f0 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68   saved. After th
1a800 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  e trigger progra
1a810 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73  m .**        has
1a820 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f   finished, the o
1a830 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73  riginal value is
1a840 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20   restored.)^.** 
1a850 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74  .**   <li> ^(Wit
1a860 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72  hin a trigger pr
1a870 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52  ogram each INSER
1a880 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45  T, UPDATE and DE
1a890 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20  LETE .**        
1a8a0 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74  statement sets t
1a8b0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1a8c0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
1a8d0 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20  nges() .**      
1a8e0 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f    upon completio
1a8f0 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20  n as normal. Of 
1a900 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c  course, this val
1a910 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c  ue will not incl
1a920 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61  ude .**        a
1a930 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f  ny changes perfo
1a940 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67  rmed by sub-trig
1a950 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c  gers, as the sql
1a960 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a  ite3_changes() .
1a970 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20  **        value 
1a980 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e  will be saved an
1a990 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72  d restored after
1a9a0 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65   each sub-trigge
1a9b0 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20  r has run.)^.** 
1a9c0 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68  </ul>.** .** ^Th
1a9d0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66  is means that if
1a9e0 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53   the changes() S
1a9f0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20  QL function (or 
1aa00 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64  similar) is used
1aa10 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74  .** by the first
1aa20 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1aa30 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
1aa40 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69  ent within a tri
1aa50 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74  gger, it .** ret
1aa60 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61  urns the value a
1aa70 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63  s set when the c
1aa80 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  alling statement
1aa90 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67   began executing
1aaa0 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75  ..** ^If it is u
1aab0 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  sed by the secon
1aac0 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  d or subsequent 
1aad0 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77  such statement w
1aae0 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
1aaf0 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65  .** program, the
1ab00 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1ab10 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d  reflects the num
1ab20 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
1ab30 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
1ab40 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c  previous INSERT,
1ab50 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
1ab60 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
1ab70 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  in the same trig
1ab80 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ger..**.** See a
1ab90 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
1aba0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
1abb0 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
1abc0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
1abd0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
1abe0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
1abf0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
1ac00 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
1ac10 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
1ac20 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
1ac30 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1ac40 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
1ac50 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
1ac60 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
1ac70 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
1ac80 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
1ac90 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
1aca0 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
1acb0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68  /.int sqlite3_ch
1acc0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
1acd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ace0 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f  : Total Number O
1acf0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
1ad00 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1ad10 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
1ad20 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1ad30 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
1ad40 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65   of rows inserte
1ad50 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a  d, modified or.*
1ad60 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c  * deleted by all
1ad70 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41   [INSERT], [UPDA
1ad80 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
1ad90 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c  statements compl
1ada0 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68  eted.** since th
1adb0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1adc0 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64  ction was opened
1add0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73  , including thos
1ade0 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a  e executed as.**
1adf0 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72   part of trigger
1ae00 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63   programs. ^Exec
1ae10 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  uting any other 
1ae20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74  type of SQL stat
1ae30 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f  ement.** does no
1ae40 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61 6c  t affect the val
1ae50 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
1ae60 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1ae70 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e  nges()..** .** ^
1ae80 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20  Changes made as 
1ae90 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e  part of [foreign
1aea0 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72   key actions] ar
1aeb0 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  e included in th
1aec0 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20  e.** count, but 
1aed0 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61  those made as pa
1aee0 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f  rt of REPLACE co
1aef0 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
1af00 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20  ion are.** not. 
1af10 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
1af20 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
1af30 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 45  rcepted by INSTE
1af40 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a  AD OF triggers .
1af50 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
1af60 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61  ed..** .** See a
1af70 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
1af80 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
1af90 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
1afa0 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
1afb0 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
1afc0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
1afd0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
1afe0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
1aff0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
1b000 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
1b010 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1b020 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
1b030 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
1b040 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
1b050 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
1b060 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
1b070 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
1b080 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
1b090 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
1b0a0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1b0b0 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
1b0c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
1b0d0 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
1b0e0 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20  unning Query.** 
1b0f0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1b100 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1b110 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
1b120 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
1b130 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
1b140 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
1b150 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
1b160 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
1b170 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
1b180 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
1b190 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
1b1a0 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
1b1b0 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
1b1c0 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
1b1d0 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
1b1e0 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
1b1f0 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
1b200 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
1b210 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
1b220 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20   ^It is safe to 
1b230 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
1b240 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20  e from a thread 
1b250 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74  different from t
1b260 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61  he.** thread tha
1b270 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72  t is currently r
1b280 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  unning the datab
1b290 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  ase operation.  
1b2a0 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74  But it.** is not
1b2b0 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
1b2c0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
1b2d0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
1b2e0 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20  ection] that.** 
1b2f0 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67  is closed or mig
1b300 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20  ht close before 
1b310 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1b320 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
1b330 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70  ** ^If an SQL op
1b340 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20  eration is very 
1b350 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
1b360 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
1b370 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  .** sqlite3_inte
1b380 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65  rrupt() is calle
1b390 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
1b3a0 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
1b3b0 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62  ortunity.** to b
1b3c0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e  e interrupted an
1b3d0 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  d might continue
1b3e0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
1b3f0 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70  **.** ^An SQL op
1b400 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
1b410 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
1b420 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1b430 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e  INTERRUPT]..** ^
1b440 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74  If the interrupt
1b450 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  ed SQL operation
1b460 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55   is an INSERT, U
1b470 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
1b480 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69  .** that is insi
1b490 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  de an explicit t
1b4a0 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
1b4b0 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
1b4c0 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20  saction.** will 
1b4d0 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
1b4e0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a  utomatically..**
1b4f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1b500 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61  _interrupt(D) ca
1b510 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20  ll is in effect 
1b520 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e  until all curren
1b530 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53  tly running.** S
1b540 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e  QL statements on
1b550 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1b560 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74  ction] D complet
1b570 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c  e.  ^Any new SQL
1b580 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1b590 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1b5a0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
1b5b0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
1b5c0 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68  ll and before th
1b5d0 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74  e .** running st
1b5e0 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73  atements reaches
1b5f0 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72   zero are interr
1b600 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79  upted as if they
1b610 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e   had been.** run
1b620 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68  ning prior to th
1b630 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1b640 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65  upt() call.  ^Ne
1b650 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
1b660 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1b670 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72  rted after the r
1b680 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
1b690 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a   count reaches z
1b6a0 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65  ero are.** not e
1b6b0 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73  ffected by the s
1b6c0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1b6d0 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  ()..** ^A call t
1b6e0 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
1b6f0 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75  upt(D) that occu
1b700 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72  rs when there ar
1b710 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  e no running.** 
1b720 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
1b730 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61  s a no-op and ha
1b740 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
1b750 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1b760 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1b770 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
1b780 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1b790 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f  call returns..*/
1b7a0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
1b7b0 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
1b7c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b7d0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
1b7e0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
1b7f0 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a  t Is Complete.**
1b800 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1b810 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75  es are useful du
1b820 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e  ring command-lin
1b830 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72  e input to deter
1b840 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63  mine if the.** c
1b850 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
1b860 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66   text seems to f
1b870 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53  orm a complete S
1b880 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a  QL statement or.
1b890 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
1b8a0 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
1b8b0 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
1b8c0 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a  the text into.**
1b8d0 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
1b8e0 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ing.  ^These rou
1b8f0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69  tines return 1 i
1b900 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
1b910 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
1b920 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
1b930 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  QL statement.  ^
1b940 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
1b950 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
1b960 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
1b970 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
1b980 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
1b990 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66   not a prefix of
1b9a0 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65   a.** well-forme
1b9b0 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  d CREATE TRIGGER
1b9c0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65   statement.  ^Se
1b9d0 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
1b9e0 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
1b9f0 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
1ba00 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
1ba10 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
1ba20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
1ba30 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
1ba40 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
1ba50 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
1ba60 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
1ba70 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
1ba80 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
1ba90 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
1baa0 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
1bab0 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61  ator.  ^Whitespa
1bac0 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e  ce.** and commen
1bad0 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74  ts that follow t
1bae0 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c  he final semicol
1baf0 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a  on are ignored..
1bb00 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
1bb10 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
1bb20 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
1bb30 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
1bb40 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ^If a.** memory 
1bb50 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
1bb60 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f  , then SQLITE_NO
1bb70 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  MEM is returned.
1bb80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
1bb90 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
1bba0 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
1bbb0 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
1bbc0 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
1bbd0 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
1bbe0 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
1bbf0 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61  * ^(If SQLite ha
1bc00 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69  s not been initi
1bc10 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71  alized using [sq
1bc20 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
1bc30 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f  ()] prior .** to
1bc40 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65   invoking sqlite
1bc50 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74  3_complete16() t
1bc60 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  hen sqlite3_init
1bc70 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
1bc80 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ked.** automatic
1bc90 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
1bca0 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49  complete16().  I
1bcb0 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a  f that initializ
1bcc0 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20  ation fails,.** 
1bcd0 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
1bce0 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
1bcf0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
1bd00 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f  will be non-zero
1bd10 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
1bd20 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
1bd30 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69   the input SQL i
1bd40 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a  s complete.)^.**
1bd50 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
1bd60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
1bd70 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
1bd80 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1bd90 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
1bda0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
1bdb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
1bdc0 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
1bdd0 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
1bde0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
1bdf0 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
1be00 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
1be10 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
1be20 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
1be30 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
1be40 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
1be50 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
1be60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1be70 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
1be80 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
1be90 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
1bea0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62  .** KEYWORDS: {b
1beb0 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy-handler call
1bec0 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64  back} {busy hand
1bed0 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ler}.** METHOD: 
1bee0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1bef0 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  he sqlite3_busy_
1bf00 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72  handler(D,X,P) r
1bf10 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61  outine sets a ca
1bf20 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1bf30 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20  X.** that might 
1bf40 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
1bf50 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65  argument P whene
1bf60 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70  ver.** an attemp
1bf70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63  t is made to acc
1bf80 65 73 73 20 61 20 64 61 74 61 62 61 73 65 20 74  ess a database t
1bf90 61 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20  able associated 
1bfa0 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  with.** [databas
1bfb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
1bfc0 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72  when another thr
1bfd0 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73  ead.** or proces
1bfe0 73 20 68 61 73 20 74 68 65 20 74 61 62 6c 65 20  s has the table 
1bff0 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73  locked..** The s
1c000 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1c010 6c 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 20  ler() interface 
1c020 69 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  is used to imple
1c030 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ment.** [sqlite3
1c040 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
1c050 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73   and [PRAGMA bus
1c060 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a  y_timeout]..**.*
1c070 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63  * ^If the busy c
1c080 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c  allback is NULL,
1c090 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55   then [SQLITE_BU
1c0a0 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  SY].** is return
1c0b0 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
1c0c0 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
1c0d0 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20   the lock.  ^If 
1c0e0 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
1c0f0 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  k.** is not NULL
1c100 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  , then the callb
1c110 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76  ack might be inv
1c120 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72  oked with two ar
1c130 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  guments..**.** ^
1c140 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
1c150 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68  nt to the busy h
1c160 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
1c170 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
1c180 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
1c190 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
1c1a0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1c1b0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20  busy_handler(). 
1c1c0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
1c1d0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20  ument to.** the 
1c1e0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c  busy handler cal
1c1f0 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d  lback is the num
1c200 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
1c210 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
1c220 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69  er has.** been i
1c230 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c  nvoked previousl
1c240 79 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c  y for the same l
1c250 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ocking event.  ^
1c260 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63  If the.** busy c
1c270 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1c280 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74  0, then no addit
1c290 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61  ional attempts a
1c2a0 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63  re made to.** ac
1c2b0 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
1c2c0 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55  e and [SQLITE_BU
1c2d0 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a  SY] is returned.
1c2e0 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ** to the applic
1c2f0 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68  ation..** ^If th
1c300 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1c310 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
1c320 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70  n another attemp
1c330 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20  t.** is made to 
1c340 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
1c350 61 73 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c  ase and the cycl
1c360 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a  e repeats..**.**
1c370 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   The presence of
1c380 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
1c390 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  does not guarant
1c3a0 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20  ee that it will 
1c3b0 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68  be invoked.** wh
1c3c0 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b  en there is lock
1c3d0 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66   contention. ^If
1c3e0 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e   SQLite determin
1c3f0 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67  es that invoking
1c400 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e   the busy.** han
1c410 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c  dler could resul
1c420 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c  t in a deadlock,
1c430 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61   it will go ahea
1c440 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  d and return [SQ
1c450 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f  LITE_BUSY].** to
1c460 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1c470 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f   instead of invo
1c480 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73  king the .** bus
1c490 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f  y handler..** Co
1c4a0 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69  nsider a scenari
1c4b0 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63  o where one proc
1c4c0 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
1c4d0 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a   read lock that.
1c4e0 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20  ** it is trying 
1c4f0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20  to promote to a 
1c500 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e  reserved lock an
1c510 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72  d.** a second pr
1c520 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
1c530 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
1c540 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69   that it is tryi
1c550 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ng.** to promote
1c560 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65   to an exclusive
1c570 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73   lock.  The firs
1c580 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  t process cannot
1c590 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61   proceed.** beca
1c5a0 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
1c5b0 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
1c5c0 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70  and the second p
1c5d0 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a  rocess cannot.**
1c5e0 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65   proceed because
1c5f0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
1c600 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66  y the first.  If
1c610 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a   both processes.
1c620 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75  ** invoke the bu
1c630 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69  sy handlers, nei
1c640 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61  ther will make a
1c650 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68  ny progress.  Th
1c660 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69  erefore,.** SQLi
1c670 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  te returns [SQLI
1c680 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65  TE_BUSY] for the
1c690 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20   first process, 
1c6a0 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73  hoping that this
1c6b0 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20  .** will induce 
1c6c0 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
1c6d0 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73  s to release its
1c6e0 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61   read lock and a
1c6f0 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f  llow.** the seco
1c700 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72  nd process to pr
1c710 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oceed..**.** ^Th
1c720 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63  e default busy c
1c730 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e  allback is NULL.
1c740 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
1c750 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
1c760 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
1c770 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63   defined for eac
1c780 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
1c790 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74  onnection].  Set
1c7a0 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20  ting a new busy 
1c7b0 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61  handler clears a
1c7c0 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ny.** previously
1c7d0 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20   set handler.)^ 
1c7e0 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c   ^Note that call
1c7f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
1c800 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20  y_timeout()].** 
1c810 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50  or evaluating [P
1c820 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
1c830 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67  ut=N] will chang
1c840 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61  e the.** busy ha
1c850 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63  ndler and thus c
1c860 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75  lear any previou
1c870 73 6c 79 20 73 65 74 20 62 75 73 79 20 68 61 6e  sly set busy han
1c880 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dler..**.** The 
1c890 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68  busy callback sh
1c8a0 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e  ould not take an
1c8b0 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20  y actions which 
1c8c0 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61  modify the.** da
1c8d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c8e0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1c8f0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
1c900 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
1c910 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  ,.** the busy ha
1c920 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65  ndler is not ree
1c930 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63  ntrant.  Any suc
1c940 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
1c950 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
1c960 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
1c970 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  * A busy handler
1c980 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
1c990 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1c9a0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70  nection.** or [p
1c9b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1c9c0 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  t] that invoked 
1c9d0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1c9e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1c9f0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71  _busy_handler(sq
1ca00 6c 69 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f  lite3*,int(*)(vo
1ca10 69 64 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b  id*,int),void*);
1ca20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ca30 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
1ca40 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  eout.** METHOD: 
1ca50 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1ca60 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
1ca70 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
1ca80 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
1ca90 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
1caa0 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
1cab0 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
1cac0 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
1cad0 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
1cae0 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  ^The handler.** 
1caf0 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
1cb00 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
1cb10 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
1cb20 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
1cb30 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
1cb40 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66  ccumulated.  ^Af
1cb50 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73  ter at least "ms
1cb60 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
1cb70 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
1cb80 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
1cb90 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
1cba0 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
1cbb0 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
1cbc0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a  [SQLITE_BUSY]..*
1cbd0 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68  *.** ^Calling th
1cbe0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
1cbf0 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73  an argument less
1cc00 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
1cc10 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20  o zero.** turns 
1cc20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e  off all busy han
1cc30 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  dlers..**.** ^(T
1cc40 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
1cc50 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
1cc60 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72  andler for a par
1cc70 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
1cc80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1cc90 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f   at any given mo
1cca0 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65  ment.  If anothe
1ccb0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  r busy handler.*
1ccc0 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28  * was defined  (
1ccd0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
1cce0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
1ccf0 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
1cd00 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
1cd10 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
1cd20 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
1cd30 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  ared.)^.**.** Se
1cd40 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41  e also:  [PRAGMA
1cd50 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a   busy_timeout].*
1cd60 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
1cd70 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
1cd80 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
1cd90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1cda0 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
1cdb0 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
1cdc0 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f  Queries.** METHO
1cdd0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1cde0 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63   This is a legac
1cdf0 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
1ce00 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f   is preserved fo
1ce10 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
1ce20 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73  atibility..** Us
1ce30 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
1ce40 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d  ace is not recom
1ce50 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65  mended..**.** De
1ce60 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
1ce70 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
1ce80 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
1ce90 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
1cea0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
1ceb0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
1cec0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
1ced0 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
1cee0 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
1cef0 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
1cf00 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
1cf10 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
1cf20 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
1cf30 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
1cf40 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
1cf50 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
1cf60 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
1cf70 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
1cf80 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1cf90 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
1cfa0 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
1cfb0 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
1cfc0 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
1cfd0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
1cfe0 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
1cff0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
1d000 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
1d010 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
1d020 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
1d030 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
1d040 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
1d050 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
1d060 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
1d070 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
1d080 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
1d090 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
1d0a0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1d0b0 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
1d0c0 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
1d0d0 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
1d0e0 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
1d0f0 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
1d100 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
1d110 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
1d120 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
1d130 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
1d140 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
1d150 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
1d160 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
1d170 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
1d180 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
1d190 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1d1a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
1d1b0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
1d1c0 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
1d1d0 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
1d1e0 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
1d1f0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
1d200 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
1d210 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
1d220 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
1d230 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1d240 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
1d250 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
1d260 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
1d270 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1d280 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  able()]..**.** ^
1d290 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f  (As an example o
1d2a0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1d2b0 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
1d2c0 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
1d2d0 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
1d2e0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1d2f0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1d300 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
1d310 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
1d320 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
1d330 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
1d340 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
1d350 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
1d360 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
1d370 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
1d380 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
1d390 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1d3a0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
1d3b0 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
1d3c0 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
1d3d0 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
1d3e0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
1d3f0 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
1d400 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
1d410 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1d420 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
1d430 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
1d440 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
1d450 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
1d460 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
1d470 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1d480 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
1d490 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
1d4a0 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
1d4b0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
1d4c0 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
1d4d0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1d4e0 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
1d4f0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1d500 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
1d510 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1d520 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
1d530 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1d540 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
1d550 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
1d560 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
1d570 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
1d580 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1d590 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
1d5a0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1d5b0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1d5c0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1d5d0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
1d5e0 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
1d5f0 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
1d600 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
1d610 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
1d620 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1d630 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
1d640 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
1d650 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
1d660 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1d670 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
1d680 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
1d690 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
1d6a0 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70  .** After the ap
1d6b0 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69  plication has fi
1d6c0 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
1d6d0 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69  result from sqli
1d6e0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
1d6f0 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73  .** it must pass
1d700 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1d710 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
1d720 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1d730 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
1d740 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1d750 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
1d760 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
1d770 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
1d780 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
1d790 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
1d7a0 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
1d7b0 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
1d7c0 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
1d7d0 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
1d7e0 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
1d7f0 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
1d800 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
1d810 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1d820 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
1d830 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
1d840 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
1d850 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
1d860 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1d870 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
1d880 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
1d890 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
1d8a0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
1d8b0 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
1d8c0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
1d8d0 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
1d8e0 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
1d8f0 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
1d900 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
1d910 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
1d920 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
1d930 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
1d940 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
1d950 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
1d960 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
1d970 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
1d980 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
1d990 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
1d9a0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1d9b0 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
1d9c0 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
1d9d0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1d9e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
1d9f0 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
1da00 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
1da10 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1da20 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
1da30 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1da40 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
1da50 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
1da60 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1da70 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
1da80 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
1da90 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
1daa0 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
1dab0 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
1dac0 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
1dad0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1dae0 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
1daf0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1db00 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
1db10 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1db20 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
1db30 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
1db40 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
1db50 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
1db60 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
1db70 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
1db80 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1db90 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
1dba0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1dbb0 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
1dbc0 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
1dbd0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1dbe0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1dbf0 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
1dc00 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
1dc10 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
1dc20 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
1dc30 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1dc40 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ry..** These rou
1dc50 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64  tines understand
1dc60 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d   most of the com
1dc70 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69  mon K&R formatti
1dc80 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70  ng options,.** p
1dc90 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  lus some additio
1dca0 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64  nal non-standard
1dcb0 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c   formats, detail
1dcc0 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74  ed below..** Not
1dcd0 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74  e that some of t
1dce0 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20  he more obscure 
1dcf0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1dd00 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a  ns from recent.*
1dd10 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e  * C-library stan
1dd20 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65  dards are omitte
1dd30 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c  d from this impl
1dd40 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ementation..**.*
1dd50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1dd60 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
1dd70 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
1dd80 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
1dd90 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
1dda0 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
1ddb0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
1ddc0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
1ddd0 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
1dde0 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74  urned by these t
1ddf0 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  wo routines shou
1de00 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65  ld be.** release
1de10 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
1de20 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f  ee()].  ^Both ro
1de30 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
1de40 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
1de50 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
1de60 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
1de70 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
1de80 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
1de90 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
1dea0 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
1deb0 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
1dec0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
1ded0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
1dee0 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
1def0 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
1df00 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
1df10 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
1df20 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
1df30 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
1df40 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1df50 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
1df60 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
1df70 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
1df80 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74  meter. Note that
1df90 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   the order of th
1dfa0 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70  e.** first two p
1dfb0 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76  arameters is rev
1dfc0 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69  ersed from snpri
1dfd0 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69  ntf().)^  This i
1dfe0 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63  s an.** historic
1dff0 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74  al accident that
1e000 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64   cannot be fixed
1e010 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1e020 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  g.** backwards c
1e030 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e  ompatibility.  ^
1e040 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20  (Note also that 
1e050 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1e060 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
1e070 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
1e080 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
1e090 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
1e0a0 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
1e0b0 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
1e0c0 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e  to the buffer.)^
1e0d0 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
1e0e0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
1e0f0 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
1e100 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
1e110 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
1e120 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
1e130 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
1e140 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
1e150 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1e160 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
1e170 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
1e180 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1e190 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61  **.** ^As long a
1e1a0 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
1e1b0 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
1e1c0 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
1e1d0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
1e1e0 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
1e1f0 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
1e200 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
1e210 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a  ed.  ^The first.
1e220 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22  ** parameter "n"
1e230 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69   is the total si
1e240 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
1e250 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63  , including spac
1e260 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72  e for.** the zer
1e270 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53  o terminator.  S
1e280 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74  o the longest st
1e290 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65  ring that can be
1e2a0 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77   completely.** w
1e2b0 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e  ritten will be n
1e2c0 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -1 characters..*
1e2d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1e2e0 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  3_vsnprintf() ro
1e2f0 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72  utine is a varar
1e300 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71  gs version of sq
1e310 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1e320 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
1e330 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65  utines all imple
1e340 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69  ment some additi
1e350 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a  onal formatting.
1e360 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  ** options that 
1e370 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
1e380 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20  onstructing SQL 
1e390 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41  statements..** A
1e3a0 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20  ll of the usual 
1e3b0 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74  printf() formatt
1e3c0 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c  ing options appl
1e3d0 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c  y.  In addition,
1e3e0 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65   there.** is are
1e3f0 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77   "%q", "%Q", "%w
1e400 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f  " and "%z" optio
1e410 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ns..**.** ^(The 
1e420 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %q option works 
1e430 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
1e440 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61  it substitutes a
1e450 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
1e460 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74  ** string from t
1e470 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  he argument list
1e480 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64  .  But %q also d
1e490 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27  oubles every '\'
1e4a0 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  ' character..** 
1e4b0 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66  %q is designed f
1e4c0 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20  or use inside a 
1e4d0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29  string literal.)
1e4e0 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  ^  By doubling e
1e4f0 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
1e500 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
1e510 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
1e520 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
1e530 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
1e540 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
1e550 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
1e560 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73  le, assume the s
1e570 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a  tring variable z
1e580 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65  Text contains te
1e590 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  xt as follows:.*
1e5a0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1e5b0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1e5c0 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61  *zText = "It's a
1e5d0 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a   happy day!";.**
1e5e0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1e5f0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63  ote>.**.** One c
1e600 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74  an use this text
1e610 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
1e620 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ment as follows:
1e630 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1e640 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1e650 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
1e660 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
1e670 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
1e680 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78  UES('%q')", zTex
1e690 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1e6a0 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1e6b0 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1e6c0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1e6d0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1e6e0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65  kquote>.**.** Be
1e6f0 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72  cause the %q for
1e700 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73  mat string is us
1e710 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61  ed, the '\'' cha
1e720 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a  racter in zText.
1e730 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e  ** is escaped an
1e740 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61  d the SQL genera
1e750 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ted is as follow
1e760 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1e770 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1e780 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1e790 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20  1 VALUES('It''s 
1e7a0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a  a happy day!').*
1e7b0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1e7c0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1e7d0 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61   is correct.  Ha
1e7e0 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73  d we used %s ins
1e7f0 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20  tead of %q, the 
1e800 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a  generated SQL.**
1e810 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b   would have look
1e820 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ed like this:.**
1e830 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1e840 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
1e850 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
1e860 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70  UES('It's a happ
1e870 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70  y day!');.** </p
1e880 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1e890 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f  .**.** This seco
1e8a0 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e  nd example is an
1e8b0 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f   SQL syntax erro
1e8c0 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c  r.  As a general
1e8d0 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64   rule you should
1e8e0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25  .** always use %
1e8f0 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20  q instead of %s 
1e900 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74  when inserting t
1e910 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e  ext into a strin
1e920 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  g literal..**.**
1e930 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e   ^(The %Q option
1e940 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
1e950 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
1e960 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
1e970 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
1e980 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
1e990 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64  tal string.  Add
1e9a0 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68  itionally, if th
1e9b0 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
1e9c0 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c  he.** argument l
1e9d0 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
1e9e0 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
1e9f0 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
1ea00 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a  NULL" (without.*
1ea10 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29  * single quotes)
1ea20 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  .)^  So, for exa
1ea30 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
1ea40 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
1ea50 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1ea60 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
1ea70 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
1ea80 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1ea90 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
1eaa0 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
1eab0 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
1eac0 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
1ead0 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
1eae0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1eaf0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1eb00 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
1eb10 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
1eb20 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
1eb30 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
1eb40 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
1eb50 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
1eb60 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
1eb70 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1eb80 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74  (The "%w" format
1eb90 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c  ting option is l
1eba0 69 6b 65 20 22 25 71 22 20 65 78 63 65 70 74 20  ike "%q" except 
1ebb0 74 68 61 74 20 69 74 20 65 78 70 65 63 74 73 20  that it expects 
1ebc0 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e  to.** be contain
1ebd0 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65  ed within double
1ebe0 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20  -quotes instead 
1ebf0 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  of single quotes
1ec00 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61  , and it.** esca
1ec10 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71  pes the double-q
1ec20 75 6f 74 65 20 63 68 61 72 61 63 74 65 72 20 69  uote character i
1ec30 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 73 69  nstead of the si
1ec40 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68  ngle-quote.** ch
1ec50 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20  aracter.)^  The 
1ec60 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%w" formatting 
1ec70 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64  option is intend
1ec80 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e  ed for safely in
1ec90 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65  serting.** table
1eca0 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   and column name
1ecb0 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75  s into a constru
1ecc0 63 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  cted SQL stateme
1ecd0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  nt..**.** ^(The 
1ece0 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%z" formatting 
1ecf0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1ed00 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20  e "%s" but with 
1ed10 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20  the.** addition 
1ed20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73  that after the s
1ed30 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72  tring has been r
1ed40 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69  ead and copied i
1ed50 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  nto.** the resul
1ed60 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  t, [sqlite3_free
1ed70 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  ()] is called on
1ed80 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
1ed90 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71  g.)^.*/.char *sq
1eda0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f  lite3_mprintf(co
1edb0 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a  nst char*,...);.
1edc0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
1edd0 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1ede0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68  r*, va_list);.ch
1edf0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72  ar *sqlite3_snpr
1ee00 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1ee10 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29  onst char*, ...)
1ee20 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
1ee30 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  vsnprintf(int,ch
1ee40 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1ee50 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a   va_list);../*.*
1ee60 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1ee70 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75  ry Allocation Su
1ee80 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68  bsystem.**.** Th
1ee90 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
1eea0 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
1eeb0 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
1eec0 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
1eed0 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
1eee0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
1eef0 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72  "Core" in the pr
1ef00 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a  evious sentence.
1ef10 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ** does not incl
1ef20 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  ude operating-sy
1ef30 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46  stem specific VF
1ef40 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
1ef50 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77  .  The.** Window
1ef60 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76  s VFS uses nativ
1ef70 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  e malloc() and f
1ef80 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f  ree() for some o
1ef90 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
1efa0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61   ^The sqlite3_ma
1efb0 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72  lloc() routine r
1efc0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1efd0 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f   to a block.** o
1efe0 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73  f memory at leas
1eff0 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e  t N bytes in len
1f000 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20  gth, where N is 
1f010 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
1f020 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
1f030 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
1f040 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
1f050 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
1f060 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
1f070 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1f080 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65    ^If the parame
1f090 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69  ter N to.** sqli
1f0a0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1f0b0 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65  zero or negative
1f0c0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61   then sqlite3_ma
1f0d0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a  lloc() returns.*
1f0e0 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
1f0f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1f100 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29  ite3_malloc64(N)
1f110 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a   routine works j
1f120 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69  ust like.** sqli
1f130 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78  te3_malloc(N) ex
1f140 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61  cept that N is a
1f150 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69  n unsigned 64-bi
1f160 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61  t integer instea
1f170 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64  d.** of a signed
1f180 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e   32-bit integer.
1f190 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
1f1a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77  sqlite3_free() w
1f1b0 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72  ith a pointer pr
1f1c0 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
1f1d0 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
1f1e0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1f1f0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
1f200 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f  leases that memo
1f210 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74  ry so.** that it
1f220 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64   might be reused
1f230 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
1f240 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69  free() routine i
1f250 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20  s.** a no-op if 
1f260 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
1f270 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1f280 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  Passing a NULL p
1f290 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c  ointer.** to sql
1f2a0 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68  ite3_free() is h
1f2b0 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20  armless.  After 
1f2c0 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d  being freed, mem
1f2d0 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65  ory.** should ne
1f2e0 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f  ither be read no
1f2f0 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e  r written.  Even
1f300 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75   reading previou
1f310 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d  sly freed.** mem
1f320 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ory might result
1f330 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69   in a segmentati
1f340 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65  on fault or othe
1f350 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a  r severe error..
1f360 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70  ** Memory corrup
1f370 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61  tion, a segmenta
1f380 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f  tion fault, or o
1f390 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1f3a0 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c  r.** might resul
1f3b0 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65  t if sqlite3_fre
1f3c0 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69  e() is called wi
1f3d0 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  th a non-NULL po
1f3e0 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61  inter that.** wa
1f3f0 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66  s not obtained f
1f400 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
1f410 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1f420 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a  realloc()..**.**
1f430 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
1f440 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72  alloc(X,N) inter
1f450 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
1f460 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
1f470 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
1f480 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20  tion X to be at 
1f490 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a  least N bytes..*
1f4a0 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61 72 61  * ^If the X para
1f4b0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1f4c0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a  _realloc(X,N).**
1f4d0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1f4e0 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61  er then its beha
1f4f0 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61  vior is identica
1f500 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  l to calling.** 
1f510 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1f520 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20  )..** ^If the N 
1f530 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1f540 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1f550 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20  ) is zero or.** 
1f560 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68  negative then th
1f570 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78  e behavior is ex
1f580 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61  actly the same a
1f590 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  s calling.** sql
1f5a0 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a  ite3_free(X)..**
1f5b0 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   ^sqlite3_reallo
1f5c0 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61  c(X,N) returns a
1f5d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
1f5e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
1f5f0 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
1f600 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
1f610 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66  r NULL if insuff
1f620 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
1f630 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e   available..** ^
1f640 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65  If M is the size
1f650 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1f660 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d  location, then m
1f670 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a  in(N,M) bytes.**
1f680 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1f690 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70  location are cop
1f6a0 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67  ied into the beg
1f6b0 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72  inning of buffer
1f6c0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1f6d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f6e0 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69  X,N) and the pri
1f6f0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
1f700 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73   freed..** ^If s
1f710 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1f720 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ,N) returns NULL
1f730 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69   and N is positi
1f740 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  ve, then the.** 
1f750 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1f760 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a   is not freed..*
1f770 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1f780 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29  3_realloc64(X,N)
1f790 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b   interfaces work
1f7a0 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a  s the same as.**
1f7b0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f7c0 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61  (X,N) except tha
1f7d0 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20  t N is a 64-bit 
1f7e0 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
1f7f0 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61   instead.** of a
1f800 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69   32-bit signed i
1f810 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  nteger..**.** ^I
1f820 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20  f X is a memory 
1f830 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69  allocation previ
1f840 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
1f850 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
1f860 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  oc(),.** sqlite3
1f870 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c  _malloc64(), sql
1f880 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20  ite3_realloc(), 
1f890 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1f8a0 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20  oc64(), then.** 
1f8b0 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
1f8c0 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a   returns the siz
1f8d0 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79  e of that memory
1f8e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62   allocation in b
1f8f0 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61  ytes..** ^The va
1f900 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1f910 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
1f920 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72   might be larger
1f930 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72   than the number
1f940 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71  .** of bytes req
1f950 75 65 73 74 65 64 20 77 68 65 6e 20 58 20 77 61  uested when X wa
1f960 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49  s allocated.  ^I
1f970 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f X is a NULL po
1f980 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71  inter then.** sq
1f990 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72  lite3_msize(X) r
1f9a0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66  eturns zero.  If
1f9b0 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d   X points to som
1f9c0 65 74 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e  ething that is n
1f9d0 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e  ot.** the beginn
1f9e0 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c  ing of memory al
1f9f0 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20  location, or if 
1fa00 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66  it points to a f
1fa10 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64  ormerly.** valid
1fa20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1fa30 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20  on that has now 
1fa40 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e  been freed, then
1fa50 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
1fa60 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a   of sqlite3_msiz
1fa70 65 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65  e(X) is undefine
1fa80 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68  d and possibly h
1fa90 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  armful..**.** ^T
1faa0 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  he memory return
1fab0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ed by sqlite3_ma
1fac0 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f  lloc(), sqlite3_
1fad0 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71  realloc(),.** sq
1fae0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
1faf0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
1fb00 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20  alloc64().** is 
1fb10 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74  always aligned t
1fb20 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20  o at least an 8 
1fb30 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f  byte boundary, o
1fb40 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65  r to a.** 4 byte
1fb50 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65   boundary if the
1fb60 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f   [SQLITE_4_BYTE_
1fb70 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20  ALIGNED_MALLOC] 
1fb80 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
1fb90 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  option is used..
1fba0 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20  **.** In SQLite 
1fbb0 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e  version 3.5.0 an
1fbc0 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20  d 3.5.1, it was 
1fbd0 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69  possible to defi
1fbe0 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45  ne.** the SQLITE
1fbf0 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c  _OMIT_MEMORY_ALL
1fc00 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f  OCATION which wo
1fc10 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75  uld cause the bu
1fc20 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ilt-in.** implem
1fc30 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73  entation of thes
1fc40 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  e routines to be
1fc50 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20   omitted.  That 
1fc60 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
1fc70 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69   no longer provi
1fc80 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74  ded.  Only built
1fc90 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
1fca0 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65  ators can be use
1fcb0 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74  d..**.** Prior t
1fcc0 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  o SQLite version
1fcd0 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e   3.7.10, the Win
1fce0 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63  dows OS interfac
1fcf0 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a  e layer called.*
1fd00 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c  * the system mal
1fd10 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
1fd20 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63   directly when c
1fd30 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c  onverting.** fil
1fd40 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74  enames between t
1fd50 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  he UTF-8 encodin
1fd60 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  g used by SQLite
1fd70 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72  .** and whatever
1fd80 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69   filename encodi
1fd90 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68  ng is used by th
1fda0 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e  e particular Win
1fdb0 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61  dows.** installa
1fdc0 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c  tion.  Memory al
1fdd0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20  location errors 
1fde0 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62  were detected, b
1fdf0 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20  ut.** they were 
1fe00 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73  reported back as
1fe10 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
1fe20 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  N] or.** [SQLITE
1fe30 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74  _IOERR] rather t
1fe40 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  han [SQLITE_NOME
1fe50 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f  M]..**.** The po
1fe60 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20  inter arguments 
1fe70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
1fe80 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1fe90 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d  _realloc()].** m
1fea0 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55  ust be either NU
1feb0 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74  LL or else point
1fec0 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ers obtained fro
1fed0 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76  m a prior.** inv
1fee0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
1fef0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
1ff00 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1ff10 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a  c()] that have.*
1ff20 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72  * not yet been r
1ff30 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eleased..**.** T
1ff40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
1ff50 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20  ust not read or 
1ff60 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f  write any part o
1ff70 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20  f.** a block of 
1ff80 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20  memory after it 
1ff90 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65  has been release
1ffa0 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
1ffb0 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b  te3_free()] or [
1ffc0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1ffd0 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  )]..*/.void *sql
1ffe0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
1fff0 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
20000 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33  malloc64(sqlite3
20010 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a  _uint64);.void *
20020 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
20030 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
20040 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
20050 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69  oc64(void*, sqli
20060 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69  te3_uint64);.voi
20070 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76  d sqlite3_free(v
20080 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75  oid*);.sqlite3_u
20090 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73  int64 sqlite3_ms
200a0 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ize(void*);../*.
200b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
200c0 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
200d0 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53  atistics.**.** S
200e0 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
200f0 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
20100 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
20110 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
20120 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
20130 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
20140 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
20150 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
20160 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
20170 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
20180 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
20190 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
201a0 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
201b0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
201c0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
201d0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
201e0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
201f0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  .** of memory cu
20200 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64  rrently outstand
20210 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75  ing (malloced bu
20220 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a  t not freed)..**
20230 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
20240 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
20250 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
20260 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  ns the maximum.*
20270 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  * value of [sqli
20280 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
20290 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67  )] since the hig
202a0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
202b0 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20  was last reset. 
202c0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
202d0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
202e0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
202f0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
20300 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
20310 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79  r()] include any
20320 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64   overhead.** add
20330 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20  ed by SQLite in 
20340 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  its implementati
20350 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
20360 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74  alloc()],.** but
20370 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64   not overhead ad
20380 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75  ded by the any u
20390 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
203a0 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74   library.** rout
203b0 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
203c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
203d0 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   call..**.** ^Th
203e0 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61  e memory high-wa
203f0 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65  ter mark is rese
20400 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  t to the current
20410 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71   value of.** [sq
20420 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
20430 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
20440 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
20450 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
20460 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
20470 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e  r()] is true.  ^
20480 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
20490 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
204a0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
204b0 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69  er(1)] is the hi
204c0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
204d0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65   prior to the re
204e0 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  set..*/.sqlite3_
204f0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
20500 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
20510 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
20520 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
20530 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
20540 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
20550 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d  API3REF: Pseudo-
20560 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65  Random Number Ge
20570 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51  nerator.**.** SQ
20580 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  Lite contains a 
20590 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
205a0 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65  udo-random numbe
205b0 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e  r generator (PRN
205c0 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65  G) used to.** se
205d0 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57  lect random [ROW
205e0 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65  ID | ROWIDs] whe
205f0 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
20600 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
20610 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
20620 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
20630 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b  rgest possible [
20640 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e  ROWID].  The PRN
20650 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
20660 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
20670 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
20680 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
20690 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
206a0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
206b0 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
206c0 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
206d0 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
206e0 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
206f0 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  *.** ^A call to 
20700 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
20710 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
20720 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
20730 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65  uffer P..** ^The
20740 20 50 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e   P parameter can
20750 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
20760 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  er..**.** ^If th
20770 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e  is routine has n
20780 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73  ot been previous
20790 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20  ly called or if 
207a0 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20  the previous.** 
207b0 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20  call had N less 
207c0 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55  than one or a NU
207d0 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50  LL pointer for P
207e0 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20  , then the PRNG 
207f0 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69  is.** seeded usi
20800 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  ng randomness ob
20810 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20  tained from the 
20820 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68  xRandomness meth
20830 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66  od of.** the def
20840 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
20850 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49  s] object..** ^I
20860 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
20870 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
20880 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20  ine had an N of 
20890 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a  1 or more and a.
208a0 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68  ** non-NULL P th
208b0 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  en the pseudo-ra
208c0 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
208d0 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
208e0 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
208f0 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
20900 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
20910 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
20920 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  hod..*/.void sql
20930 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
20940 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
20950 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20960 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
20970 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
20980 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44  lbacks.** METHOD
20990 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45 59  : sqlite3.** KEY
209a0 57 4f 52 44 53 3a 20 7b 61 75 74 68 6f 72 69 7a  WORDS: {authoriz
209b0 65 72 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a  er callback}.**.
209c0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
209d0 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75   registers an au
209e0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
209f0 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
20a00 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
20a10 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
20a20 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
20a30 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
20a40 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
20a50 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
20a60 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
20a70 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
20a80 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
20a90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20aa0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
20ab0 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
20ac0 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
20ad0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20ae0 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v3()], [sqlite3_
20af0 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 5b 73  prepare16()], [s
20b00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
20b10 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b  _v2()],.** and [
20b20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20b30 36 5f 76 33 28 29 5d 2e 20 20 5e 41 74 20 76 61  6_v3()].  ^At va
20b40 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
20b50 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
20b60 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
20b70 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
20b80 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
20b90 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
20ba0 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
20bb0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
20bc0 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
20bd0 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
20be0 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
20bf0 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72  ed.  ^The author
20c00 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68  izer callback sh
20c10 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
20c20 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c  SQLITE_OK] to al
20c30 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20  low the action, 
20c40 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
20c50 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a  to disallow the.
20c60 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69  ** specific acti
20c70 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65  on but allow the
20c80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
20c90 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  o continue to be
20ca0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72  .** compiled, or
20cb0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74   [SQLITE_DENY] t
20cc0 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  o cause the enti
20cd0 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  re SQL statement
20ce0 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74   to be.** reject
20cf0 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ed with an error
20d00 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  .  ^If the autho
20d10 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
20d20 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61  eturns.** any va
20d30 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
20d40 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
20d50 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
20d60 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a  [SQLITE_DENY].**
20d70 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   then the [sqlit
20d80 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
20d90 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
20da0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
20db0 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  ed.** the author
20dc0 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
20dd0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
20de0 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  sage..**.** When
20df0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
20e00 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
20e10 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ], that means th
20e20 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72  e operation.** r
20e30 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20  equested is ok. 
20e40 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62   ^When the callb
20e50 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
20e60 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
20e70 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
20e80 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
20e90 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
20ea0 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a   triggered the.*
20eb0 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  * authorizer wil
20ec0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
20ed0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70  rror message exp
20ee0 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20  laining that.** 
20ef0 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64  access is denied
20f00 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  . .**.** ^The fi
20f10 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
20f20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
20f30 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
20f40 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a  py of the third.
20f50 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
20f60 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
20f70 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74  authorizer() int
20f80 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63  erface. ^The sec
20f90 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
20fa0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
20fb0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b   is an integer [
20fc0 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
20fd0 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
20fe0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
20ff0 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69   particular acti
21000 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
21010 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20  zed. ^The third 
21020 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61  through sixth pa
21030 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74  rameters.** to t
21040 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20  he callback are 
21050 65 69 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69 6e  either NULL poin
21060 74 65 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65 72  ters or zero-ter
21070 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 0a  minated strings.
21080 2a 2a 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20  ** that contain 
21090 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69  additional detai
210a0 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
210b0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
210c0 69 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  ized..** Applica
210d0 74 69 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61 79  tions must alway
210e0 73 20 62 65 20 70 72 65 70 61 72 65 64 20 74 6f  s be prepared to
210f0 20 65 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55 4c   encounter a NUL
21100 4c 20 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e 79  L pointer in any
21110 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 69 72 64  .** of the third
21120 20 74 68 72 6f 75 67 68 20 74 68 65 20 73 69 78   through the six
21130 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  th parameters of
21140 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
21150 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  on callback..**.
21160 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
21170 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
21180 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74  E_READ].** and t
21190 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
211a0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  rns [SQLITE_IGNO
211b0 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  RE] then the.** 
211c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
211d0 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  ent] statement i
211e0 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f  s constructed to
211f0 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61   substitute.** a
21200 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70   NULL value in p
21210 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c  lace of the tabl
21220 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f  e column that wo
21230 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e  uld have.** been
21240 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
21250 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
21260 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51  turned.  The [SQ
21270 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20  LITE_IGNORE].** 
21280 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73  return can be us
21290 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e  ed to deny an un
212a0 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63  trusted user acc
212b0 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61  ess to individua
212c0 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  l.** columns of 
212d0 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65  a table..** ^Whe
212e0 6e 20 61 20 74 61 62 6c 65 20 69 73 20 72 65 66  n a table is ref
212f0 65 72 65 6e 63 65 64 20 62 79 20 61 20 5b 53 45  erenced by a [SE
21300 4c 45 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f 6c  LECT] but no col
21310 75 6d 6e 20 76 61 6c 75 65 73 20 61 72 65 0a 2a  umn values are.*
21320 2a 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  * extracted from
21330 20 74 68 61 74 20 74 61 62 6c 65 20 28 66 6f 72   that table (for
21340 20 65 78 61 6d 70 6c 65 20 69 6e 20 61 20 71 75   example in a qu
21350 65 72 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c  ery like.** "SEL
21360 45 43 54 20 63 6f 75 6e 74 28 2a 29 20 46 52 4f  ECT count(*) FRO
21370 4d 20 74 61 62 22 29 20 74 68 65 6e 20 74 68 65  M tab") then the
21380 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61   [SQLITE_READ] a
21390 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
213a0 63 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  ck.** is invoked
213b0 20 6f 6e 63 65 20 66 6f 72 20 74 68 61 74 20 74   once for that t
213c0 61 62 6c 65 20 77 69 74 68 20 61 20 63 6f 6c 75  able with a colu
213d0 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20  mn name that is 
213e0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e  an empty string.
213f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
21400 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
21410 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
21420 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
21430 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
21440 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
21450 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
21460 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
21470 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
21480 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
21490 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
214a0 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
214b0 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
214c0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
214d0 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
214e0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
214f0 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
21500 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
21510 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
21520 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
21530 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
21540 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
21550 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
21560 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
21570 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
21580 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
21590 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
215a0 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
215b0 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
215c0 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
215d0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
215e0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
215f0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
21600 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
21610 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
21620 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
21630 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
21640 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
21650 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
21660 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
21670 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
21680 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
21690 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
216a0 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
216b0 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
216c0 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
216d0 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
216e0 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
216f0 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
21700 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
21710 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
21720 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
21730 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
21740 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
21750 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
21760 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
21770 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
21780 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
21790 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
217a0 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
217b0 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
217c0 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
217d0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
217e0 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
217f0 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
21800 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
21810 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
21820 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
21830 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
21840 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
21850 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
21860 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
21870 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
21880 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
21890 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
218a0 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
218b0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
218c0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
218d0 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
218e0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
218f0 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
21900 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
21910 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
21920 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
21930 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
21940 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
21950 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
21960 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21970 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
21980 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
21990 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
219a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
219b0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
219c0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
219d0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
219e0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
219f0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
21a00 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21a10 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
21a20 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
21a30 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
21a40 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
21a50 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
21a60 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
21a70 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
21a80 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
21a90 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
21aa0 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
21ab0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
21ac0 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
21ad0 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
21ae0 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
21af0 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
21b00 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
21b10 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
21b20 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
21b30 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
21b40 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21b50 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
21b60 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
21b70 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
21b80 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
21b90 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
21ba0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
21bb0 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
21bc0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
21bd0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
21be0 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
21bf0 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
21c00 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
21c10 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
21c20 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
21c30 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
21c40 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
21c50 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
21c60 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
21c70 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
21c80 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
21c90 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
21ca0 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
21cb0 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
21cc0 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
21cd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
21ce0 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
21cf0 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
21d00 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
21d10 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
21d20 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
21d30 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
21d40 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
21d50 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
21d60 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
21d70 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
21d80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
21d90 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
21da0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
21db0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
21dc0 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
21dd0 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
21de0 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
21df0 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
21e00 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
21e10 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
21e20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
21e30 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
21e40 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
21e50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
21e60 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
21e70 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
21e80 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
21e90 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
21ea0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ation..**.** Not
21eb0 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47  e that SQLITE_IG
21ec0 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65  NORE is also use
21ed0 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74  d as a [conflict
21ee0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65   resolution mode
21ef0 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72  ].** returned fr
21f00 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
21f10 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74  vtab_on_conflict
21f20 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
21f30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21f40 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
21f50 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
21f60 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
21f70 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
21f80 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
21f90 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
21fa0 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
21fb0 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
21fc0 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
21fd0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
21fe0 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
21ff0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
22000 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
22010 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
22020 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
22030 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
22040 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
22050 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
22060 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
22070 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
22080 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
22090 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
220a0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
220b0 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
220c0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
220d0 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
220e0 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
220f0 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
22100 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
22110 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
22120 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
22130 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
22140 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
22150 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
22160 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
22170 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
22180 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
22190 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
221a0 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
221b0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
221c0 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
221d0 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
221e0 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
221f0 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
22200 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
22210 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
22220 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
22230 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
22240 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
22250 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
22260 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
22270 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
22280 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
22290 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
222a0 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
222b0 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
222c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
222d0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
222e0 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
222f0 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
22300 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
22310 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
22320 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
22330 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
22340 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
22350 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
22360 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
22370 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
22380 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
22390 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
223a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
223b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
223c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
223d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
223e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
223f0 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
22400 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
22410 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
22420 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
22430 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
22440 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
22450 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
22460 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
22470 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22480 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
22490 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
224a0 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
224b0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
224c0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
224d0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
224e0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
224f0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22500 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22510 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22520 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
22530 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
22540 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
22550 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
22560 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22570 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
22580 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
22590 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
225a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
225b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
225c0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
225d0 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
225e0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
225f0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
22600 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22610 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
22620 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
22630 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
22640 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22650 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22660 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
22670 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
22680 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22690 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
226a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
226b0 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
226c0 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
226d0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
226e0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
226f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22700 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
22710 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
22720 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
22730 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22740 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22750 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
22760 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
22770 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
22780 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22790 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
227a0 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
227b0 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
227c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
227d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
227e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
227f0 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
22800 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
22810 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
22820 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
22830 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22840 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
22850 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
22860 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
22870 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22880 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22890 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
228a0 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
228b0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
228c0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
228d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
228e0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
228f0 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
22900 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
22910 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22920 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
22930 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
22940 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
22950 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
22960 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22970 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
22980 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
22990 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
229a0 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
229b0 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
229c0 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
229d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
229e0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
229f0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
22a00 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
22a10 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
22a20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
22a30 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
22a40 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22a50 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22a60 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
22a70 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
22a80 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
22a90 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22aa0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22ab0 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
22ac0 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
22ad0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
22ae0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
22af0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22b00 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
22b10 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
22b20 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
22b30 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22b40 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22b50 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
22b60 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
22b70 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
22b80 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22b90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22ba0 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
22bb0 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
22bc0 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
22bd0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22be0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22bf0 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
22c00 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
22c10 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
22c20 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22c30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22c40 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
22c50 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
22c60 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
22c70 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22c80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22c90 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
22ca0 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
22cb0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
22cc0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
22cd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22ce0 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
22cf0 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
22d00 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
22d10 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
22d20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
22d30 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
22d40 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
22d50 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
22d60 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
22d70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
22d80 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
22d90 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
22da0 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
22db0 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
22dc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
22dd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22de0 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
22df0 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69  er used */.#defi
22e00 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53  ne SQLITE_RECURS
22e10 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33  IVE            3
22e20 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  3   /* NULL     
22e30 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
22e40 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a         */../*.**
22e50 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
22e60 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
22e70 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45   Functions.** ME
22e80 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
22e90 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
22ea0 65 73 20 61 72 65 20 64 65 70 72 65 63 61 74 65  es are deprecate
22eb0 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69  d. Use the [sqli
22ec0 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20  te3_trace_v2()] 
22ed0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73  interface.** ins
22ee0 74 65 61 64 20 6f 66 20 74 68 65 20 72 6f 75 74  tead of the rout
22ef0 69 6e 65 73 20 64 65 73 63 72 69 62 65 64 20 68  ines described h
22f00 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ere..**.** These
22f10 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74   routines regist
22f20 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
22f30 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62  tions that can b
22f40 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72  e used for.** tr
22f50 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c  acing and profil
22f60 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
22f70 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  n of SQL stateme
22f80 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
22f90 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
22fa0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
22fb0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
22fc0 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
22fd0 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
22fe0 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
22ff0 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
23000 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
23010 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  ep()]..** ^The s
23020 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
23030 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
23040 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20  ed with a UTF-8 
23050 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
23060 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
23070 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74  t text as the st
23080 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
23090 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a  gins executing..
230a0 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20  ** ^(Additional 
230b0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
230c0 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20  callbacks might 
230d0 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68  occur.** as each
230e0 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72   triggered subpr
230f0 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64  ogram is entered
23100 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73  .  The callbacks
23110 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a   for triggers.**
23120 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38   contain a UTF-8
23130 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61   SQL comment tha
23140 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  t identifies the
23150 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a   trigger.)^.**.*
23160 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52  * The [SQLITE_TR
23170 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20  ACE_SIZE_LIMIT] 
23180 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
23190 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
231a0 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20  to limit.** the 
231b0 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64  length of [bound
231c0 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61   parameter] expa
231d0 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74  nsion in the out
231e0 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74  put of sqlite3_t
231f0 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  race()..**.** ^T
23200 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
23210 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
23220 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
23230 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
23240 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
23250 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
23260 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  s.  ^The profile
23270 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
23280 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  ns.** the origin
23290 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  al statement tex
232a0 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74  t and an estimat
232b0 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  e of wall-clock 
232c0 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c  time.** of how l
232d0 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
232e0 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20  nt took to run. 
232f0 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
23300 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69  llback.** time i
23310 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61  s in units of na
23320 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76  noseconds, howev
23330 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  er the current i
23340 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
23350 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65   is only capable
23360 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20   of millisecond 
23370 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68  resolution so th
23380 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e  e six least sign
23390 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74  ificant.** digit
233a0 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72  s in the time ar
233b0 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20  e meaningless.  
233c0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
233d0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67  of SQLite.** mig
233e0 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74  ht provide great
233f0 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e  er resolution on
23400 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61   the profiler ca
23410 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20  llback.  The.** 
23420 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
23430 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f  ) function is co
23440 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d  nsidered experim
23450 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20  ental and is.** 
23460 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
23470 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  e in future vers
23480 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
23490 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  */.SQLITE_DEPREC
234a0 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74  ATED void *sqlit
234b0 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
234c0 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 61  *,.   void(*xTra
234d0 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
234e0 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
234f0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
23500 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  D void *sqlite3_
23510 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
23520 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
23530 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
23540 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
23550 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
23560 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23570 20 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74   SQL Trace Event
23580 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
23590 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45  DS: SQLITE_TRACE
235a0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
235b0 73 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20  stants identify 
235c0 63 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74  classes of event
235d0 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f  s that can be mo
235e0 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67  nitored.** using
235f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72   the [sqlite3_tr
23600 61 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e  ace_v2()] tracin
23610 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 74 68  g logic.  The th
23620 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
23630 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  to [sqlite3_trac
23640 65 5f 76 32 28 29 5d 20 69 73 20 61 6e 20 4f 52  e_v2()] is an OR
23650 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  -ed combination 
23660 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  of one or more o
23670 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
23680 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e  ng constants.  ^
23690 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
236a0 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20  nt to the trace 
236b0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f  callback.** is o
236c0 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
236d0 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a  ing constants..*
236e0 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67  *.** New tracing
236f0 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62   constants may b
23700 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
23710 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a  e releases..**.*
23720 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62  * ^A trace callb
23730 61 63 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67  ack has four arg
23740 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63  uments: xCallbac
23750 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e  k(T,C,P,X)..** ^
23760 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69  The T argument i
23770 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74  s one of the int
23780 65 67 65 72 20 74 79 70 65 20 63 6f 64 65 73 20  eger type codes 
23790 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43  above..** ^The C
237a0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63   argument is a c
237b0 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
237c0 78 74 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  xt pointer passe
237d0 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
237e0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
237f0 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  o [sqlite3_trace
23800 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50  _v2()]..** The P
23810 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73   and X arguments
23820 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68   are pointers wh
23830 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70  ose meanings dep
23840 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20  end on T..**.** 
23850 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
23860 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64  _TRACE_STMT]] <d
23870 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53  t>SQLITE_TRACE_S
23880 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TMT</dt>.** <dd>
23890 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ^An SQLITE_TRACE
238a0 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69  _STMT callback i
238b0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61  s invoked when a
238c0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
238d0 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67  ent.** first beg
238e0 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20  ins running and 
238f0 70 6f 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65  possibly at othe
23900 72 20 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74  r times during t
23910 68 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20  he.** execution 
23920 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20  of the prepared 
23930 73 74 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20  statement, such 
23940 61 73 20 61 74 20 74 68 65 20 73 74 61 72 74 20  as at the start 
23950 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67  of each.** trigg
23960 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e  er subprogram. ^
23970 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
23980 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
23990 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
239a0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65  statement]. ^The
239b0 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   X argument is a
239c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
239d0 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73  ring which.** is
239e0 20 74 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20   the unexpanded 
239f0 53 51 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20  SQL text of the 
23a00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23a10 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d  nt or an SQL com
23a20 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e  ment .** that in
23a30 64 69 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f  dicates the invo
23a40 63 61 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67  cation of a trig
23a50 67 65 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62  ger.  ^The callb
23a60 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a  ack can compute.
23a70 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 65 78 74  ** the same text
23a80 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
23a90 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62   been returned b
23aa0 79 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  y the legacy [sq
23ab0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a  lite3_trace()].*
23ac0 2a 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 75  * interface by u
23ad0 73 69 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d  sing the X argum
23ae0 65 6e 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e  ent when X begin
23af0 73 20 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20  s with "--" and 
23b00 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c  invoking.** [sql
23b10 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
23b20 6c 28 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e  l(P)] otherwise.
23b30 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
23b40 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20  TRACE_PROFILE]] 
23b50 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45  <dt>SQLITE_TRACE
23b60 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a  _PROFILE</dt>.**
23b70 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f   <dd>^An SQLITE_
23b80 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61  TRACE_PROFILE ca
23b90 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20  llback provides 
23ba0 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68  approximately th
23bb0 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d  e same.** inform
23bc0 61 74 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76  ation as is prov
23bd0 69 64 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ided by the [sql
23be0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20  ite3_profile()] 
23bf0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68  callback..** ^Th
23c00 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
23c10 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
23c20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23c30 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a  ment] and the.**
23c40 20 58 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e   X argument poin
23c50 74 73 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69  ts to a 64-bit i
23c60 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
23c70 74 68 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66  the estimated of
23c80 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
23c90 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61  f nanosecond tha
23ca0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
23cb0 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
23cc0 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51   run..** ^The SQ
23cd0 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
23ce0 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  LE callback is i
23cf0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20  nvoked when the 
23d00 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
23d10 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  es..**.** [[SQLI
23d20 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c  TE_TRACE_ROW]] <
23d30 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  dt>SQLITE_TRACE_
23d40 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ROW</dt>.** <dd>
23d50 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ^An SQLITE_TRACE
23d60 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73  _ROW callback is
23d70 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
23d80 72 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  r a prepared.** 
23d90 73 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61  statement genera
23da0 74 65 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77  tes a single row
23db0 20 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a   of result.  .**
23dc0 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
23dd0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
23de0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
23df0 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68  tatement] and th
23e00 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20  e.** X argument 
23e10 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  is unused..**.**
23e20 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f   [[SQLITE_TRACE_
23e30 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CLOSE]] <dt>SQLI
23e40 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f  TE_TRACE_CLOSE</
23e50 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53  dt>.** <dd>^An S
23e60 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
23e70 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  E callback is in
23e80 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74  voked when a dat
23e90 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
23ea0 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e  ion closes..** ^
23eb0 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
23ec0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
23ed0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
23ee0 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a  nection] object.
23ef0 2a 2a 20 61 6e 64 20 74 68 65 20 58 20 61 72 67  ** and the X arg
23f00 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e  ument is unused.
23f10 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
23f20 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43  fine SQLITE_TRAC
23f30 45 5f 53 54 4d 54 20 20 20 20 20 20 20 30 78 30  E_STMT       0x0
23f40 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
23f50 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20  _TRACE_PROFILE  
23f60 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53    0x02.#define S
23f70 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20  QLITE_TRACE_ROW 
23f80 20 20 20 20 20 20 20 30 78 30 34 0a 23 64 65 66         0x04.#def
23f90 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ine SQLITE_TRACE
23fa0 5f 43 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38  _CLOSE      0x08
23fb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23fc0 3a 20 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b  : SQL Trace Hook
23fd0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
23fe0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
23ff0 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
24000 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61  D,M,X,P) interfa
24010 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 74  ce registers a t
24020 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  race callback.**
24030 20 66 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69   function X agai
24040 6e 73 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f  nst [database co
24050 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69  nnection] D, usi
24060 6e 67 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b  ng property mask
24070 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78   M.** and contex
24080 74 20 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49  t pointer P.  ^I
24090 66 20 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b  f the X callback
240a0 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69   is.** NULL or i
240b0 66 20 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20  f the M mask is 
240c0 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69  zero, then traci
240d0 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20  ng is disabled. 
240e0 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65   The.** M argume
240f0 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
24100 20 62 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63   bitwise OR-ed c
24110 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a  ombination of.**
24120 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53   zero or more [S
24130 51 4c 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e  QLITE_TRACE] con
24140 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45  stants..**.** ^E
24150 61 63 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68  ach call to eith
24160 65 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  er sqlite3_trace
24170 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72  () or sqlite3_tr
24180 61 63 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64  ace_v2() overrid
24190 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29  es .** (cancels)
241a0 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73   any prior calls
241b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63   to sqlite3_trac
241c0 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74  e() or sqlite3_t
241d0 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  race_v2()..**.**
241e0 20 5e 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b   ^The X callback
241f0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
24200 65 76 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20  ever any of the 
24210 65 76 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65  events identifie
24220 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20  d by .** mask M 
24230 6f 63 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74  occur.  ^The int
24240 65 67 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75  eger return valu
24250 65 20 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62  e from the callb
24260 61 63 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ack is currently
24270 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f  .** ignored, tho
24280 75 67 68 20 74 68 69 73 20 6d 61 79 20 63 68 61  ugh this may cha
24290 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 72 65  nge in future re
242a0 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63  leases.  Callbac
242b0 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  k.** implementat
242c0 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75  ions should retu
242d0 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72  rn zero to ensur
242e0 65 20 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69  e future compati
242f0 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
24300 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
24310 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
24320 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20  four arguments: 
24330 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58  callback(T,C,P,X
24340 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67  )..** ^The T arg
24350 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
24360 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  the [SQLITE_TRAC
24370 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20  E].** constants 
24380 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 79 20  to indicate why 
24390 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73  the callback was
243a0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68   invoked..** ^Th
243b0 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e C argument is 
243c0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  a copy of the co
243d0 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  ntext pointer..*
243e0 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72  * The P and X ar
243f0 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e  guments are poin
24400 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69  ters whose meani
24410 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e  ngs depend on T.
24420 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
24430 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e  e3_trace_v2() in
24440 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e  terface is inten
24450 64 65 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74  ded to replace t
24460 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
24470 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
24480 5f 74 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73  _trace()] and [s
24490 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
244a0 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68  ], both of which
244b0 0a 2a 2a 20 61 72 65 20 64 65 70 72 65 63 61 74  .** are deprecat
244c0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
244d0 65 33 5f 74 72 61 63 65 5f 76 32 28 0a 20 20 73  e3_trace_v2(.  s
244e0 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67  qlite3*,.  unsig
244f0 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74  ned uMask,.  int
24500 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73  (*xCallback)(uns
24510 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64  igned,void*,void
24520 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  *,void*),.  void
24530 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a   *pCtx.);../*.**
24540 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
24550 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
24560 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  cks.** METHOD: s
24570 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
24580 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  e sqlite3_progre
24590 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58  ss_handler(D,N,X
245a0 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  ,P) interface ca
245b0 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  uses the callbac
245c0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20  k.** function X 
245d0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65  to be invoked pe
245e0 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
245f0 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63  g long running c
24600 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
24610 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
24620 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
24630 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  d [sqlite3_get_t
24640 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64  able()] for.** d
24650 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24660 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c  on D.  An exampl
24670 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a  e use for this.*
24680 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
24690 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64  o keep a GUI upd
246a0 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61  ated during a la
246b0 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a  rge query..**.**
246c0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
246d0 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  P is passed thro
246e0 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ugh as the only 
246f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
24700 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75   .** callback fu
24710 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20  nction X.  ^The 
24720 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74  parameter N is t
24730 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e  he approximate n
24740 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69  umber of .** [vi
24750 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e  rtual machine in
24760 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74  structions] that
24770 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62   are evaluated b
24780 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76  etween successiv
24790 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
247a0 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   of the callback
247b0 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65   X.  ^If N is le
247c0 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e  ss than one then
247d0 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a   the progress.**
247e0 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61   handler is disa
247f0 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  bled..**.** ^Onl
24800 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72  y a single progr
24810 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20  ess handler may 
24820 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e  be defined at on
24830 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64  e time per.** [d
24840 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24850 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e  on]; setting a n
24860 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  ew progress hand
24870 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a  ler cancels the.
24880 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65  ** old one.  ^Se
24890 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  tting parameter 
248a0 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c  X to NULL disabl
248b0 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  es the progress 
248c0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65  handler..** ^The
248d0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
248e0 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c  r is also disabl
248f0 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20  ed by setting N 
24900 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a  to a value less.
24910 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a  ** than 1..**.**
24920 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73   ^If the progres
24930 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
24940 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
24950 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a   operation is.**
24960 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54   interrupted.  T
24970 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20  his feature can 
24980 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  be used to imple
24990 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65  ment a.** "Cance
249a0 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47  l" button on a G
249b0 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c  UI progress dial
249c0 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68  og box..**.** Th
249d0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
249e0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
249f0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
24a00 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
24a10 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
24a20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
24a30 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72  t invoked the pr
24a40 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
24a50 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
24a60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
24a70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
24a80 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
24a90 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
24aa0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24ab0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
24ac0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
24ad0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
24ae0 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ..**.*/.void sql
24af0 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
24b00 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
24b10 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
24b20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
24b30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
24b40 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
24b50 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
24b60 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73  * CONSTRUCTOR: s
24b70 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
24b80 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
24b90 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
24ba0 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65  base file as spe
24bb0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  cified by the .*
24bc0 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
24bd0 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61  ent. ^The filena
24be0 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
24bf0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
24c00 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
24c10 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
24c20 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
24c30 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
24c40 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
24c50 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
24c60 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
24c70 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ^(A [database co
24c80 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
24c90 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
24ca0 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
24cb0 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
24cc0 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
24cd0 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
24ce0 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
24cf0 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
24d00 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
24d10 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
24d20 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
24d30 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
24d40 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
24d50 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
24d60 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
24d70 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
24d80 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20  ect.)^ ^(If the 
24d90 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
24da0 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
24db0 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
24dc0 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
24dd0 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
24de0 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
24df0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
24e00 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68   returned.)^ ^Th
24e10 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
24e20 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
24e30 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
24e40 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
24e50 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
24e60 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
24e70 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
24e80 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66  n of the error f
24e90 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75  ollowing a failu
24ea0 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  re of any.** of 
24eb0 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  the sqlite3_open
24ec0 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  () routines..**.
24ed0 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
24ee0 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65  encoding will be
24ef0 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62   UTF-8 for datab
24f00 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73 69  ases created usi
24f10 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  ng.** sqlite3_op
24f20 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
24f30 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65  open_v2().  ^The
24f40 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
24f50 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a  g for databases.
24f60 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  ** created using
24f70 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
24f80 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36  ) will be UTF-16
24f90 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
24fa0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
24fb0 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   Whether or not 
24fc0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
24fd0 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65  when it is opene
24fe0 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20  d, resources.** 
24ff0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
25000 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
25010 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
25020 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61   should be relea
25030 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e  sed by.** passin
25040 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
25050 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69  _close()] when i
25060 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
25070 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
25080 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  he sqlite3_open_
25090 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
250a0 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
250b0 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65  3_open().** exce
250c0 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70  pt that it accep
250d0 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  ts two additiona
250e0 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72  l parameters for
250f0 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74   additional cont
25100 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  rol.** over the 
25110 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
25120 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20  nection.  ^(The 
25130 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
25140 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
25150 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65  en_v2() can take
25160 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66   one of.** the f
25170 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76  ollowing three v
25180 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c  alues, optionall
25190 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
251a0 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
251b0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
251c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
251d0 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
251e0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
251f0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  ],.** [SQLITE_OP
25200 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
25210 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  , and/or [SQLITE
25220 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73  _OPEN_URI] flags
25230 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  :)^.**.** <dl>.*
25240 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
25250 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f  OPEN_READONLY]</
25260 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
25270 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
25280 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d in read-only m
25290 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74  ode.  If the dat
252a0 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
252b0 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  * already exist,
252c0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
252d0 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
252e0 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
252f0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
25300 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
25310 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
25320 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
25330 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
25340 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
25350 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
25360 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
25370 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
25380 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
25390 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
253a0 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
253b0 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
253c0 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
253d0 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
253e0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
253f0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
25400 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
25410 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
25420 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a  EN_CREATE]</dt>.
25430 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
25440 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
25450 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
25460 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72  iting, and is cr
25470 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64  eated if.** it d
25480 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20  oes not already 
25490 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74  exist. This is t
254a0 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  he behavior that
254b0 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
254c0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
254d0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
254e0 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e  3_open16().</dd>
254f0 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  )^.** </dl>.**.*
25500 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
25510 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
25520 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e  3_open_v2() is n
25530 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
25540 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
25550 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e  own above option
25560 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
25570 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c  th other.** [SQL
25580 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
25590 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  Y | SQLITE_OPEN_
255a0 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20  * bits].** then 
255b0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
255c0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
255d0 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
255e0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
255f0 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e  lag is set, then
25600 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
25610 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e  nnection.** open
25620 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74  s in the multi-t
25630 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
25640 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61   mode] as long a
25650 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72  s the single-thr
25660 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20  ead.** mode has 
25670 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20  not been set at 
25680 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
25690 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66  start-time.  ^If
256a0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
256b0 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20  OPEN_FULLMUTEX] 
256c0 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e  flag is set then
256d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
256e0 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a  nnection opens.*
256f0 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69  * in the seriali
25700 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
25710 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67  ode] unless sing
25720 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a  le-thread was.**
25730 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65   previously sele
25740 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d  cted at compile-
25750 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
25760 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  me..** ^The [SQL
25770 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
25780 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
25790 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
257a0 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a  onnection to be.
257b0 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75  ** eligible to u
257c0 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  se [shared cache
257d0 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65   mode], regardle
257e0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
257f0 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63   not shared.** c
25800 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20  ache is enabled 
25810 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  using [sqlite3_e
25820 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
25830 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20  he()].  ^The.** 
25840 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
25850 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20  VATECACHE] flag 
25860 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
25870 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
25880 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69  o not.** partici
25890 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20  pate in [shared 
258a0 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e  cache mode] even
258b0 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65   if it is enable
258c0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
258d0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
258e0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
258f0 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
25900 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
25910 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
25920 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
25930 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
25940 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
25950 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
25960 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
25970 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20  hould use.  ^If 
25980 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
25990 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
259a0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
259b0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
259c0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
259d0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  is used..**.** ^
259e0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
259f0 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
25a00 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
25a10 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
25a20 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
25a30 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
25a40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
25a50 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
25a60 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
25a70 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
25a80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25a90 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
25aa0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
25ab0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
25ac0 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
25ad0 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
25ae0 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
25af0 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
25b00 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
25b10 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
25b20 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
25b30 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
25b40 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
25b50 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
25b60 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
25b70 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
25b80 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
25b90 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
25ba0 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
25bb0 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
25bc0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
25bd0 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
25be0 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
25bf0 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
25c00 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
25c10 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
25c20 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
25c30 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
25c40 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
25c50 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
25c60 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
25c70 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
25c80 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
25c90 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
25ca0 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74  lenames in sqlit
25cb0 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e  e3_open()]] <h3>
25cc0 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68  URI Filenames</h
25cd0 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52  3>.**.** ^If [UR
25ce0 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65  I filename] inte
25cf0 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
25d00 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66  abled, and the f
25d10 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
25d20 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20  .** begins with 
25d30 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68  "file:", then th
25d40 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e  e filename is in
25d50 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55  terpreted as a U
25d60 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65  RI. ^URI.** file
25d70 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
25d80 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ion is enabled i
25d90 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
25da0 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a  EN_URI] flag is.
25db0 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f  ** set in the fo
25dc0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
25dd0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
25de0 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73  (), or if it has
25df0 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64  .** been enabled
25e00 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20   globally using 
25e10 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
25e20 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77  IG_URI] option w
25e30 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ith the.** [sqli
25e40 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65  te3_config()] me
25e50 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b  thod or by the [
25e60 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
25e70 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
25e80 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51  ion..** As of SQ
25e90 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
25ea0 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .7, URI filename
25eb0 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
25ec0 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a  is turned off.**
25ed0 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74   by default, but
25ee0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
25ef0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
25f00 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65   enable URI file
25f10 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  name.** interpre
25f20 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c  tation by defaul
25f30 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69  t.  See "[URI fi
25f40 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64  lenames]" for ad
25f50 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
25f60 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55  rmation..**.** U
25f70 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  RI filenames are
25f80 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e   parsed accordin
25f90 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e  g to RFC 3986. ^
25fa0 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61  If the URI conta
25fb0 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72  ins an.** author
25fc0 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73  ity, then it mus
25fd0 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65  t be either an e
25fe0 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74  mpty string or t
25ff0 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c  he string .** "l
26000 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74  ocalhost". ^If t
26010 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20  he authority is 
26020 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72  not an empty str
26030 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73  ing or "localhos
26040 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72  t", an .** error
26050 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20   is returned to 
26060 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65  the caller. ^The
26070 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e   fragment compon
26080 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66  ent of a URI, if
26090 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73   .** present, is
260a0 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
260b0 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
260c0 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20   path component 
260d0 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68  of the URI as th
260e0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69  e name of the di
260f0 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68  sk file.** which
26100 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61   contains the da
26110 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20  tabase. ^If the 
26120 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68  path begins with
26130 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72   a '/' character
26140 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  , .** then it is
26150 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
26160 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
26170 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64  . ^If the path d
26180 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a  oes not begin .*
26190 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65  * with a '/' (me
261a0 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61  aning that the a
261b0 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e  uthority section
261c0 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
261d0 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65   the URI).** the
261e0 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e  n the path is in
261f0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72  terpreted as a r
26200 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a  elative path. .*
26210 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20  * ^(On windows, 
26220 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e  the first compon
26230 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75  ent of an absolu
26240 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61  te path .** is a
26250 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61   drive specifica
26260 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29  tion (e.g. "C:")
26270 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65  .)^.**.** [[core
26280 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d   URI query param
26290 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71  eters]].** The q
262a0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
262b0 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74  f a URI may cont
262c0 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ain parameters t
262d0 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65  hat are interpre
262e0 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79  ted.** either by
262f0 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20   SQLite itself, 
26300 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63  or by a [VFS | c
26310 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d  ustom VFS implem
26320 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51  entation]..** SQ
26330 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75 69  Lite and its bui
26340 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e  lt-in [VFSes] in
26350 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66  terpret the.** f
26360 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70  ollowing query p
26370 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a  arameters:.**.**
26380 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
26390 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65  <b>vfs</b>: ^The
263a0 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72   "vfs" parameter
263b0 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20   may be used to 
263c0 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65  specify the name
263d0 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53   of.**     a VFS
263e0 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f   object that pro
263f0 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74  vides the operat
26400 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
26410 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64  face that should
26420 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20  .**     be used 
26430 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
26440 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64  tabase file on d
26450 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70  isk. ^If this op
26460 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a  tion is set to.*
26470 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73  *     an empty s
26480 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c  tring the defaul
26490 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20  t VFS object is 
264a0 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e  used. ^Specifyin
264b0 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20  g an unknown.** 
264c0 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72      VFS is an er
264d0 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  ror. ^If sqlite3
264e0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
264f0 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f  ed and the vfs o
26500 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
26510 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68  present, then th
26520 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20  e VFS specified 
26530 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61  by the option ta
26540 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f  kes precedence o
26550 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76  ver.**     the v
26560 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
26570 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
26580 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
26590 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
265a0 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f    <li> <b>mode</
265b0 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70  b>: ^(The mode p
265c0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
265d0 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72  set to either "r
265e0 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20  o", "rw",.**    
265f0 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f   "rwc", or "memo
26600 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20  ry". Attempting 
26610 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79  to set it to any
26620 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a   other value is.
26630 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29  **     an error)
26640 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22  ^. .**     ^If "
26650 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64  ro" is specified
26660 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
26670 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
26680 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20  r read-only .** 
26690 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74      access, just
266a0 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49   as if the [SQLI
266b0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
266c0 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20  ] flag had been 
266d0 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20  set in the .**  
266e0 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e     third argumen
266f0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
26700 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20  n_v2(). ^If the 
26710 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73  mode option is s
26720 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72  et to .**     "r
26730 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  w", then the dat
26740 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
26750 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28  for read-write (
26760 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20  but not create) 
26770 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
26780 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45  as if SQLITE_OPE
26790 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74  N_READWRITE (but
267a0 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e   not SQLITE_OPEN
267b0 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a  _CREATE) had .**
267c0 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e       been set. ^
267d0 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65  Value "rwc" is e
267e0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
267f0 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20  ting both .**   
26800 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45    SQLITE_OPEN_RE
26810 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49  ADWRITE and SQLI
26820 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20  TE_OPEN_CREATE. 
26830 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
26840 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73  tion is.**     s
26850 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74  et to "memory" t
26860 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d  hen a pure [in-m
26870 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20  emory database] 
26880 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73  that never reads
26890 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65  .**     or write
268a0 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75  s from disk is u
268b0 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65  sed. ^It is an e
268c0 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20  rror to specify 
268d0 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20  a value for.**  
268e0 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61     the mode para
268f0 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65  meter that is le
26900 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74  ss restrictive t
26910 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69  han that specifi
26920 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65  ed by.**     the
26930 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e   flags passed in
26940 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
26950 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
26960 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
26970 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65     <li> <b>cache
26980 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65  </b>: ^The cache
26990 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
269a0 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
269b0 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20  "shared" or.**  
269c0 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53     "private". ^S
269d0 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68  etting it to "sh
269e0 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c  ared" is equival
269f0 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
26a00 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  he.**     SQLITE
26a10 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
26a20 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61  E bit in the fla
26a30 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  gs argument pass
26a40 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c  ed to.**     sql
26a50 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
26a60 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63  ^Setting the cac
26a70 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  he parameter to 
26a80 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a  "private" is .**
26a90 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20       equivalent 
26aa0 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53  to setting the S
26ab0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
26ac0 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20  TECACHE bit..** 
26ad0 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f      ^If sqlite3_
26ae0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
26af0 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65  d and the "cache
26b00 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  " parameter is p
26b10 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20  resent in.**    
26b20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c   a URI filename,
26b30 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72   its value overr
26b40 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f  ides any behavio
26b50 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73  r requested by s
26b60 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51  etting.**     SQ
26b70 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
26b80 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45  ECACHE or SQLITE
26b90 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
26ba0 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c  E flag..**.**  <
26bb0 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a  li> <b>psow</b>:
26bc0 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d   ^The psow param
26bd0 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20 77  eter indicates w
26be0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
26bf0 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73  e.**     [powers
26c00 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70  afe overwrite] p
26c10 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20  roperty does or 
26c20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74  does not apply t
26c30 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f  o the.**     sto
26c40 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68  rage media on wh
26c50 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65  ich the database
26c60 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a   file resides..*
26c70 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f  *.**  <li> <b>no
26c80 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e  lock</b>: ^The n
26c90 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20  olock parameter 
26ca0 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65  is a boolean que
26cb0 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  ry parameter.** 
26cc0 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65 74      which if set
26cd0 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c   disables file l
26ce0 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61  ocking in rollba
26cf0 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73  ck journal modes
26d00 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69  .  This.**     i
26d10 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63  s useful for acc
26d20 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61 73  essing a databas
26d30 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65  e on a filesyste
26d40 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a  m that does not.
26d50 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c  **     support l
26d60 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e  ocking.  Caution
26d70 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72 72  :  Database corr
26d80 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73  uption might res
26d90 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20  ult if two.**   
26da0 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73    or more proces
26db0 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68 65  ses write to the
26dc0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 61   same database a
26dd0 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68  nd any one of th
26de0 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65  ose.**     proce
26df0 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b  sses uses nolock
26e00 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  =1..**.**  <li> 
26e10 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e  <b>immutable</b>
26e20 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65  : ^The immutable
26e30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
26e40 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a  boolean query.**
26e50 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 74       parameter t
26e60 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68  hat indicates th
26e70 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
26e80 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f  file is stored o
26e90 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e  n.**     read-on
26ea0 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e  ly media.  ^When
26eb0 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65   immutable is se
26ec0 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  t, SQLite assume
26ed0 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20  s that the.**   
26ee0 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20    database file 
26ef0 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
26f00 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f  d, even by a pro
26f10 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65 72  cess with higher
26f20 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67  .**     privileg
26f30 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61  e, and so the da
26f40 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
26f50 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61   read-only and a
26f60 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20  ll locking.**   
26f70 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74    and change det
26f80 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c  ection is disabl
26f90 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65  ed.  Caution: Se
26fa0 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61  tting the immuta
26fb0 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65  ble.**     prope
26fc0 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73  rty on a databas
26fd0 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73  e file that does
26fe0 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20   in fact change 
26ff0 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20  can result.**   
27000 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71    in incorrect q
27010 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64  uery results and
27020 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  /or [SQLITE_CORR
27030 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20  UPT] errors..** 
27040 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53      See also: [S
27050 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
27060 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20  TABLE]..**      
27070 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a   .** </ul>.**.**
27080 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
27090 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65  unknown paramete
270a0 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63  r in the query c
270b0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
270c0 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65  I is not an.** e
270d0 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65  rror.  Future ve
270e0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
270f0 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e   might understan
27100 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65  d additional que
27110 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  ry.** parameters
27120 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70  .  See "[query p
27130 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73  arameters with s
27140 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74  pecial meaning t
27150 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a  o SQLite]" for.*
27160 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
27170 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
27180 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  [[URI filename e
27190 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52  xamples]] <h3>UR
271a0 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
271b0 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c  les</h3>.**.** <
271c0 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
271d0 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65   align=center ce
271e0 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20  llpadding=5>.** 
271f0 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c  <tr><th> URI fil
27200 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75  enames <th> Resu
27210 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  lts.** <tr><td> 
27220 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64  file:data.db <td
27230 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
27240 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
27250 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
27260 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e  rrent directory.
27270 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
27280 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
27290 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20  a.db<br>.**     
272a0 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d       file:///hom
272b0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
272c0 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  br> .**         
272d0 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73   file://localhos
272e0 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  t/home/fred/data
272f0 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a  .db <br> <td> .*
27300 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
27310 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
27320 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  e "/home/fred/da
27330 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c  ta.db"..** <tr><
27340 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73  td> file://darks
27350 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  tar/home/fred/da
27360 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
27370 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72          An error
27380 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20  . "darkstar" is 
27390 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64  not a recognized
273a0 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c   authority..** <
273b0 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68  tr><td style="wh
273c0 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70  ite-space:nowrap
273d0 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  "> .**          
273e0 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d  file:///C:/Docum
273f0 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74  ents%20and%20Set
27400 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74  tings/fred/Deskt
27410 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20  op/data.db.**   
27420 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f    <td> Windows o
27430 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69  nly: Open the fi
27440 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20  le "data.db" on 
27450 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f  fred's desktop o
27460 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20  n drive.**      
27470 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61      C:. Note tha
27480 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69  t the %20 escapi
27490 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70  ng in this examp
274a0 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74  le is not strict
274b0 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ly .**          
274c0 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63  necessary - spac
274d0 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e  e characters can
274e0 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c   be used literal
274f0 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ly.**          i
27500 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e  n URI filenames.
27510 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
27520 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
27530 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20  o&cache=private 
27540 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
27550 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74    Open file "dat
27560 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
27570 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66  rent directory f
27580 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63  or read-only acc
27590 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ess..**         
275a0 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   Regardless of w
275b0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
275c0 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20  ared-cache mode 
275d0 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a  is enabled by.**
275e0 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c            defaul
275f0 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65  t, use a private
27600 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c   cache..** <tr><
27610 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
27620 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d  red/data.db?vfs=
27630 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64  unix-dotfile <td
27640 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70  >.**          Op
27650 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  en file "/home/f
27660 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73  red/data.db". Us
27670 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  e the special VF
27680 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22  S "unix-dotfile"
27690 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61  .**          tha
276a0 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73  t uses dot-files
276b0 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73   in place of pos
276c0 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b  ix advisory lock
276d0 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ing..** <tr><td>
276e0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
276f0 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e  de=readonly <td>
27700 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
27710 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c   error. "readonl
27720 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69  y" is not a vali
27730 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65  d option for the
27740 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65   "mode" paramete
27750 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  r..** </table>.*
27760 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65  *.** ^URI hexade
27770 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
27780 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65  uences (%HH) are
27790 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69   supported withi
277a0 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a  n the path and.*
277b0 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  * query componen
277c0 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68  ts of a URI. A h
277d0 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
277e0 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69  e sequence consi
277f0 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63  sts of a.** perc
27800 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d  ent sign - "%" -
27810 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61   followed by exa
27820 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63  ctly two hexadec
27830 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20  imal digits .** 
27840 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63  specifying an oc
27850 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f  tet value. ^Befo
27860 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71  re the path or q
27870 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
27880 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65  of a.** URI file
27890 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72  name are interpr
278a0 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65  eted, they are e
278b0 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46  ncoded using UTF
278c0 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68  -8 and all .** h
278d0 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
278e0 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c  e sequences repl
278f0 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65  aced by a single
27900 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67   byte containing
27910 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f   the.** correspo
27920 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20  nding octet. If 
27930 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e  this process gen
27940 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69  erates an invali
27950 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  d UTF-8 encoding
27960 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73  ,.** the results
27970 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
27980 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
27990 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c   Windows users:<
279a0 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e  /b>  The encodin
279b0 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66  g used for the f
279c0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
279d0 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  .** of sqlite3_o
279e0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
279f0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74  3_open_v2() must
27a00 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77   be UTF-8, not w
27a10 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70  hatever.** codep
27a20 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  age is currently
27a30 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e   defined.  Filen
27a40 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ames containing 
27a50 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a  international.**
27a60 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74   characters must
27a70 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
27a80 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20   UTF-8 prior to 
27a90 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74  passing them int
27aa0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
27ab0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
27ac0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
27ad0 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
27ae0 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73  ws Runtime users
27af0 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f  :</b>  The tempo
27b00 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d  rary directory m
27b10 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72  ust be set.** pr
27b20 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73  ior to calling s
27b30 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
27b40 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
27b50 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20  ().  Otherwise, 
27b60 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75  various.** featu
27b70 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65  res that require
27b80 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70   the use of temp
27b90 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20  orary files may 
27ba0 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  fail..**.** See 
27bb0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74  also: [sqlite3_t
27bc0 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a  emp_directory].*
27bd0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  /.int sqlite3_op
27be0 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
27bf0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
27c00 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
27c10 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
27c20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
27c30 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
27c40 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
27c50 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
27c60 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
27c70 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
27c80 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
27c90 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
27ca0 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
27cb0 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
27cc0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
27cd0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
27ce0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
27cf0 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
27d00 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
27d10 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
27d20 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
27d30 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
27d40 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
27d50 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
27d60 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
27d70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
27d80 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
27d90 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
27da0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
27db0 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
27dc0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
27dd0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56  PI3REF: Obtain V
27de0 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61  alues For URI Pa
27df0 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54  rameters.**.** T
27e00 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79  hese are utility
27e10 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75   routines, usefu
27e20 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65  l to VFS impleme
27e30 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63  ntations, that c
27e40 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69  heck.** to see i
27e50 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  f a database fil
27e60 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74  e was a URI that
27e70 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65   contained a spe
27e80 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20  cific query .** 
27e90 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69  parameter, and i
27ea0 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65  f so obtains the
27eb0 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71   value of that q
27ec0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a  uery parameter..
27ed0 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68  **.** If F is th
27ee0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  e database filen
27ef0 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73  ame pointer pass
27f00 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
27f10 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a  n() method of .*
27f20 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  * a VFS implemen
27f30 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20  tation when the 
27f40 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
27f50 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f  to xOpen() has o
27f60 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f  ne or .** more o
27f70 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
27f80 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49  EN_URI] or [SQLI
27f90 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
27fa0 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a   bits set and.**
27fb0 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f   P is the name o
27fc0 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61  f the query para
27fd0 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73  meter, then.** s
27fe0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
27ff0 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
28000 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
28010 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65  he P.** paramete
28020 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f  r if it exists o
28030 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
28040 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61   if P does not a
28050 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71  ppear as a .** q
28060 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
28070 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20  n F.  If P is a 
28080 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
28090 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65  of F.** has no e
280a0 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74  xplicit value, t
280b0 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
280c0 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
280d0 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e  eturns.** a poin
280e0 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  ter to an empty 
280f0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
28100 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
28110 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
28120 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61  tine assumes tha
28130 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  t P is a boolean
28140 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e  .** parameter an
28150 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  d returns true (
28160 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20  1) or false (0) 
28170 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65  according to the
28180 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20   value.** of P. 
28190 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
281a0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
281b0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
281c0 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a  true (1) if the.
281d0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72  ** value of quer
281e0 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
281f0 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22   one of "yes", "
28200 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69  true", or "on" i
28210 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72  n any.** case or
28220 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
28230 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d  gins with a non-
28240 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68  zero number.  Th
28250 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  e .** sqlite3_ur
28260 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
28270 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
28280 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74  s false (0) if t
28290 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71  he value of.** q
282a0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
282b0 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c   is one of "no",
282c0 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66   "false", or "of
282d0 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f  f" in any case o
282e0 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75  r.** if the valu
282f0 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  e begins with a 
28300 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49  numeric zero.  I
28310 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65  f P is not a que
28320 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  ry.** parameter 
28330 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76  on F or if the v
28340 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65  alue of P is doe
28350 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20  s not match any 
28360 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c  of the.** above,
28370 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
28380 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
28390 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e   returns (B!=0).
283a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
283b0 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50  e3_uri_int64(F,P
283c0 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76  ,D) routine conv
283d0 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f  erts the value o
283e0 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34  f P into a.** 64
283f0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
28400 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ger and returns 
28410 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72  that integer, or
28420 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74   D if P does not
28430 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74  .** exist.  If t
28440 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
28450 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
28460 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72   than an integer
28470 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69  , then.** zero i
28480 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a  s returned..** .
28490 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c  ** If F is a NUL
284a0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
284b0 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
284c0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
284d0 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73  ns NULL and.** s
284e0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
284f0 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
28500 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f  s B.  If F is no
28510 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  t a NULL pointer
28520 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61   and.** is not a
28530 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70   database file p
28540 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  athname pointer 
28550 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73  that SQLite pass
28560 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
28570 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c  n.** VFS method,
28580 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
28590 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  or of this routi
285a0 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  ne is undefined 
285b0 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20  and probably.** 
285c0 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a  undesirable..*/.
285d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
285e0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
285f0 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  r(const char *zF
28600 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63  ilename, const c
28610 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e  har *zParam);.in
28620 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  t sqlite3_uri_bo
28630 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72  olean(const char
28640 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63   *zFile, const c
28650 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74  har *zParam, int
28660 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69   bDefault);.sqli
28670 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
28680 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73  3_uri_int64(cons
28690 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63  t char*, const c
286a0 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  har*, sqlite3_in
286b0 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t64);.../*.** CA
286c0 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
286d0 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
286e0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
286f0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  te3.**.** ^If th
28700 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71  e most recent sq
28710 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
28720 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
28730 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63   .** [database c
28740 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69  onnection] D fai
28750 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71  led, then the sq
28760 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29  lite3_errcode(D)
28770 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65   interface.** re
28780 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
28790 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
287a0 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  or [extended res
287b0 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
287c0 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a  at.** API call..
287d0 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  ** If the most r
287e0 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77  ecent API call w
287f0 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a  as successful,.*
28800 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
28810 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
28820 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
28830 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
28840 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
28850 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
28860 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
28870 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
28880 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
28890 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
288a0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
288b0 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
288c0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
288d0 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
288e0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
288f0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
28900 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
28910 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
28920 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
28930 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
28940 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
28950 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
28960 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
28970 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
28980 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
28990 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
289a0 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
289b0 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
289c0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
289d0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
289e0 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
289f0 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
28a00 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
28a10 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
28a20 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
28a30 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
28a40 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
28a50 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
28a60 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
28a70 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
28a80 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
28a90 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69  lite3_errstr() i
28aa0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
28ab0 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e   the English-lan
28ac0 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68  guage text.** th
28ad0 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
28ae0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20   [result code], 
28af0 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d  as UTF-8..** ^(M
28b00 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
28b10 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
28b20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
28b30 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  d internally.** 
28b40 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  and must not be 
28b50 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70  freed by the app
28b60 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a  lication)^..**.*
28b70 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
28b80 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
28b90 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
28ba0 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
28bb0 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
28bc0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
28bd0 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
28be0 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
28bf0 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
28c00 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
28c10 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
28c20 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
28c30 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
28c40 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
28c50 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
28c60 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
28c70 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
28c80 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
28c90 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
28ca0 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
28cb0 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
28cc0 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
28cd0 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
28ce0 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
28cf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
28d00 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
28d10 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
28d20 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
28d30 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
28d40 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
28d50 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
28d60 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
28d70 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
28d80 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
28d90 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
28da0 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
28db0 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
28dc0 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
28dd0 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
28de0 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
28df0 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
28e00 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
28e10 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
28e20 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
28e30 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
28e40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
28e50 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
28e60 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
28e70 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
28e80 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
28e90 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  et..*/.int sqlit
28ea0 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
28eb0 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c  e3 *db);.int sql
28ec0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
28ed0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
28ee0 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  b);.const char *
28ef0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
28f00 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
28f10 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72  void *sqlite3_er
28f20 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29  rmsg16(sqlite3*)
28f30 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
28f40 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74  lite3_errstr(int
28f50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28f60 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 61  EF: Prepared Sta
28f70 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
28f80 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70   KEYWORDS: {prep
28f90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20  ared statement} 
28fa0 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
28fb0 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ents}.**.** An i
28fc0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
28fd0 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
28fe0 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  s a single SQL s
28ff0 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a  tatement that.**
29000 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c   has been compil
29010 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66  ed into binary f
29020 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79  orm and is ready
29030 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
29040 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66  ..**.** Think of
29050 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
29060 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61 74  ent as a separat
29070 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72  e computer progr
29080 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67  am.  The.** orig
29090 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73  inal SQL text is
290a0 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41   source code.  A
290b0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
290c0 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69  ent object .** i
290d0 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f  s the compiled o
290e0 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c  bject code.  All
290f0 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e   SQL must be con
29100 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a  verted into a.**
29110 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
29120 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63 61  ent before it ca
29130 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20  n be run..**.** 
29140 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f  The life-cycle o
29150 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  f a prepared sta
29160 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73  tement object us
29170 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20  ually goes like 
29180 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
29190 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
291a0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
291b0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73  tement object us
291c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
291d0 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c  pare_v2()]..** <
291e0 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
291f0 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20  to [parameters] 
29200 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
29210 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
29220 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
29230 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
29240 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
29250 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
29260 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
29270 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
29280 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
29290 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
292a0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
292b0 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20  hen go back.**  
292c0 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20      to step 2.  
292d0 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20  Do this zero or 
292e0 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
292f0 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20  li> Destroy the 
29300 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
29310 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
29320 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74  ]..** </ol>.*/.t
29330 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
29340 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
29350 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
29360 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
29370 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54  me Limits.** MET
29380 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
29390 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
293a0 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
293b0 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
293c0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
293d0 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
293e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
293f0 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
29400 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
29410 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
29420 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
29430 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
29440 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
29450 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
29460 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
29470 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
29480 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
29490 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
294a0 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
294b0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
294c0 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
294d0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
294e0 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
294f0 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
29500 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a  onstruct.)^.**.*
29510 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69  * ^If the new li
29520 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
29530 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
29540 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
29550 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20  ..** ^(For each 
29560 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53  limit category S
29570 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e  QLITE_LIMIT_<i>N
29580 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73  AME</i> there is
29590 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
295a0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
295b0 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d  d].** set at com
295c0 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43  pile-time by a C
295d0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
295e0 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c  cro called.** [l
295f0 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
29600 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e  AX_<i>NAME</i>].
29610 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
29620 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
29630 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
29640 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74  AX_".))^.** ^Att
29650 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
29660 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
29670 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
29680 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
29690 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
296a0 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
296b0 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52   bound..**.** ^R
296c0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
296d0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
296e0 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65  limit was change
296f0 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  d, the .** [sqli
29700 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74  te3_limit()] int
29710 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
29720 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
29730 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  f the limit..** 
29740 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20  ^Hence, to find 
29750 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
29760 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74  e of a limit wit
29770 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74  hout changing it
29780 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f  ,.** simply invo
29790 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ke this interfac
297a0 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64  e with the third
297b0 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74   parameter set t
297c0 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d  o -1..**.** Run-
297d0 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
297e0 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
297f0 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
29800 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
29810 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
29820 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
29830 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
29840 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
29850 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
29860 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
29870 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
29880 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
29890 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
298a0 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74  web browser that
298b0 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
298c0 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
298d0 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
298e0 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
298f0 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
29900 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
29910 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
29920 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
29930 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
29940 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
29950 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
29960 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
29970 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
29980 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
29990 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
299a0 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
299b0 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
299c0 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
299d0 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
299e0 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
299f0 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
29a00 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
29a10 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
29a20 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
29a30 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
29a40 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
29a50 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
29a60 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
29a70 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
29a80 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
29a90 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
29aa0 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
29ab0 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
29ac0 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
29ad0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
29ae0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
29af0 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
29b00 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
29b10 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
29b20 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eases..*/.int sq
29b30 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69  lite3_limit(sqli
29b40 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e  te3*, int id, in
29b50 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a  t newVal);../*.*
29b60 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
29b70 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67  Time Limit Categ
29b80 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ories.** KEYWORD
29b90 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  S: {limit catego
29ba0 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65  ry} {*limit cate
29bb0 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  gories}.**.** Th
29bc0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ese constants de
29bd0 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72  fine various per
29be0 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a  formance limits.
29bf0 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c  ** that can be l
29c00 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69  owered at run-ti
29c10 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  me using [sqlite
29c20 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
29c30 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74  he synopsis of t
29c40 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
29c50 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
29c60 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77  s is shown below
29c70 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20  ..** Additional 
29c80 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61  information is a
29c90 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d  vailable at [lim
29ca0 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20  its | Limits in 
29cb0 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  SQLite]..**.** <
29cc0 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
29cd0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e  LIMIT_LENGTH]] ^
29ce0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
29cf0 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  T_LENGTH</dt>.**
29d00 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
29d10 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72   size of any str
29d20 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74  ing or BLOB or t
29d30 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74  able row, in byt
29d40 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  es.<dd>)^.**.** 
29d50 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  [[SQLITE_LIMIT_S
29d60 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  QL_LENGTH]] ^(<d
29d70 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  t>SQLITE_LIMIT_S
29d80 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  QL_LENGTH</dt>.*
29d90 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29da0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53  m length of an S
29db0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e  QL statement, in
29dc0 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a   bytes.</dd>)^.*
29dd0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
29de0 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c  MIT_COLUMN]] ^(<
29df0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
29e00 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
29e10 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
29e20 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
29e30 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
29e40 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
29e50 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
29e60 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20  f a [SELECT] or 
29e70 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
29e80 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
29e90 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20   an index.** or 
29ea0 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f  in an ORDER BY o
29eb0 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
29ec0 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
29ed0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  [[SQLITE_LIMIT_E
29ee0 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  XPR_DEPTH]] ^(<d
29ef0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  t>SQLITE_LIMIT_E
29f00 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  XPR_DEPTH</dt>.*
29f10 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29f20 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70  m depth of the p
29f30 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79  arse tree on any
29f40 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64   expression.</dd
29f50 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
29f60 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
29f70 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74  D_SELECT]] ^(<dt
29f80 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
29f90 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
29fa0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
29fb0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
29fc0 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
29fd0 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
29fe0 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ment.</dd>)^.**.
29ff0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2a000 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64  T_VDBE_OP]] ^(<d
2a010 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
2a020 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
2a030 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
2a040 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
2a050 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
2a060 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
2a070 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
2a080 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
2a090 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 5b 73  tatement.  If [s
2a0a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2a0b0 32 28 29 5d 20 6f 72 0a 2a 2a 20 74 68 65 20 65  2()] or.** the e
2a0c0 71 75 69 76 61 6c 65 6e 74 20 74 72 69 65 73 20  quivalent tries 
2a0d0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 73 70 61 63  to allocate spac
2a0e0 65 20 66 6f 72 20 6d 6f 72 65 20 74 68 61 6e 20  e for more than 
2a0f0 74 68 69 73 20 6d 61 6e 79 20 6f 70 63 6f 64 65  this many opcode
2a100 73 0a 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c 65  s.** in a single
2a110 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2a120 65 6e 74 2c 20 61 6e 20 53 51 4c 49 54 45 5f 4e  ent, an SQLITE_N
2a130 4f 4d 45 4d 20 65 72 72 6f 72 20 69 73 20 72 65  OMEM error is re
2a140 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
2a150 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2a160 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
2a170 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2a180 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
2a190 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  RG</dt>.** <dd>T
2a1a0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
2a1b0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f  r of arguments o
2a1c0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64  n a function.</d
2a1d0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2a1e0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
2a1f0 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ED]] ^(<dt>SQLIT
2a200 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
2a210 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2a220 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
2a230 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74  of [ATTACH | att
2a240 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d  ached databases]
2a250 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  .)^</dd>.**.** [
2a260 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  [SQLITE_LIMIT_LI
2a270 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
2a280 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  H]].** ^(<dt>SQL
2a290 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
2a2a0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64  ATTERN_LENGTH</d
2a2b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2a2c0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2a2d0 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75  the pattern argu
2a2e0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b  ment to the [LIK
2a2f0 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20  E] or.** [GLOB] 
2a300 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29  operators.</dd>)
2a310 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2a320 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
2a330 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64  NUMBER]].** ^(<d
2a340 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
2a350 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f  ARIABLE_NUMBER</
2a360 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2a370 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d  aximum index num
2a380 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61  ber of any [para
2a390 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c  meter] in an SQL
2a3a0 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a   statement.)^.**
2a3b0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2a3c0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
2a3d0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2a3e0 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
2a3f0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
2a400 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
2a410 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66  h of recursion f
2a420 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64  or triggers.</dd
2a430 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2a440 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
2a450 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e  THREADS]] ^(<dt>
2a460 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52  SQLITE_LIMIT_WOR
2a470 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e  KER_THREADS</dt>
2a480 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2a490 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75  mum number of au
2a4a0 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74  xiliary worker t
2a4b0 68 72 65 61 64 73 20 74 68 61 74 20 61 20 73 69  hreads that a si
2a4c0 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65  ngle.** [prepare
2a4d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79  d statement] may
2a4e0 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a   start.</dd>)^.*
2a4f0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
2a500 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2a510 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
2a520 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
2a530 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2a540 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20  _SQL_LENGTH     
2a550 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
2a560 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2a570 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20  T_COLUMN        
2a580 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64              2.#d
2a590 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2a5a0 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20  IT_EXPR_DEPTH   
2a5b0 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23               3.#
2a5c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2a5d0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
2a5e0 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a  ECT           4.
2a5f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2a600 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20  IMIT_VDBE_OP    
2a610 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
2a620 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a630 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
2a640 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RG              
2a650 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
2a660 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20  _LIMIT_ATTACHED 
2a670 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a680 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
2a690 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
2a6a0 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20  TERN_LENGTH     
2a6b0 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
2a6c0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
2a6d0 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20  E_NUMBER        
2a6e0 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
2a6f0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
2a700 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
2a710 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
2a720 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
2a730 52 5f 54 48 52 45 41 44 53 20 20 20 20 20 20 20  R_THREADS       
2a740 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41      11../*.** CA
2a750 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 20  PI3REF: Prepare 
2a760 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  Flags.**.** Thes
2a770 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
2a780 6e 65 20 76 61 72 69 6f 75 73 20 66 6c 61 67 73  ne various flags
2a790 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 61 73   that can be pas
2a7a0 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 22 70 72 65  sed into.** "pre
2a7b0 70 46 6c 61 67 73 22 20 70 61 72 61 6d 65 74 65  pFlags" paramete
2a7c0 72 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  r of the [sqlite
2a7d0 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20  3_prepare_v3()] 
2a7e0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2a7f0 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20  prepare16_v3()] 
2a800 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 0a 2a  interfaces..**.*
2a810 2a 20 4e 65 77 20 66 6c 61 67 73 20 6d 61 79 20  * New flags may 
2a820 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
2a830 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
2a840 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  QLite..**.** <dl
2a850 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 52  >.** [[SQLITE_PR
2a860 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54  EPARE_PERSISTENT
2a870 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2a880 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45  PREPARE_PERSISTE
2a890 4e 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  NT</dt>.** <dd>T
2a8a0 68 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52  he SQLITE_PREPAR
2a8b0 45 5f 50 45 52 53 49 53 54 45 4e 54 20 66 6c 61  E_PERSISTENT fla
2a8c0 67 20 69 73 20 61 20 68 69 6e 74 20 74 6f 20 74  g is a hint to t
2a8d0 68 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  he query planner
2a8e0 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 65  .** that the pre
2a8f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2a900 77 69 6c 6c 20 62 65 20 72 65 74 61 69 6e 65 64  will be retained
2a910 20 66 6f 72 20 61 20 6c 6f 6e 67 20 74 69 6d 65   for a long time
2a920 20 61 6e 64 0a 2a 2a 20 70 72 6f 62 61 62 6c 79   and.** probably
2a930 20 72 65 75 73 65 64 20 6d 61 6e 79 20 74 69 6d   reused many tim
2a940 65 73 2e 29 5e 20 5e 57 69 74 68 6f 75 74 20 74  es.)^ ^Without t
2a950 68 69 73 20 66 6c 61 67 2c 20 5b 73 71 6c 69 74  his flag, [sqlit
2a960 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
2a970 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2a980 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
2a990 20 61 73 73 75 6d 65 20 74 68 61 74 20 74 68 65   assume that the
2a9a0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2a9b0 65 6e 74 20 77 69 6c 6c 20 0a 2a 2a 20 62 65 20  ent will .** be 
2a9c0 75 73 65 64 20 6a 75 73 74 20 6f 6e 63 65 20 6f  used just once o
2a9d0 72 20 61 74 20 6d 6f 73 74 20 61 20 66 65 77 20  r at most a few 
2a9e0 74 69 6d 65 73 20 61 6e 64 20 74 68 65 6e 20 64  times and then d
2a9f0 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67 0a 2a  estroyed using.*
2aa00 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
2aa10 69 7a 65 28 29 5d 20 72 65 6c 61 74 69 76 65 6c  ize()] relativel
2aa20 79 20 73 6f 6f 6e 2e 20 54 68 65 20 63 75 72 72  y soon. The curr
2aa30 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
2aa40 6f 6e 20 61 63 74 73 0a 2a 2a 20 6f 6e 20 74 68  on acts.** on th
2aa50 69 73 20 68 69 6e 74 20 62 79 20 61 76 6f 69 64  is hint by avoid
2aa60 69 6e 67 20 74 68 65 20 75 73 65 20 6f 66 20 5b  ing the use of [
2aa70 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
2aa80 5d 20 73 6f 20 61 73 20 6e 6f 74 20 74 6f 0a 2a  ] so as not to.*
2aa90 2a 20 64 65 70 6c 65 74 65 20 74 68 65 20 6c 69  * deplete the li
2aaa0 6d 69 74 65 64 20 73 74 6f 72 65 20 6f 66 20 6c  mited store of l
2aab0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
2aac0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
2aad0 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61   of.** SQLite ma
2aae0 79 20 61 63 74 20 6f 6e 20 74 68 69 73 20 68 69  y act on this hi
2aaf0 6e 74 20 64 69 66 66 65 72 65 6e 74 6c 79 2e 0a  nt differently..
2ab00 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
2ab10 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41  ine SQLITE_PREPA
2ab20 52 45 5f 50 45 52 53 49 53 54 45 4e 54 20 20 20  RE_PERSISTENT   
2ab30 20 20 20 20 20 20 20 20 20 20 20 30 78 30 31 0a             0x01.
2ab40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ab50 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
2ab60 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
2ab70 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
2ab80 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
2ab90 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
2aba0 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43  ite3.** CONSTRUC
2abb0 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  TOR: sqlite3_stm
2abc0 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  t.**.** To execu
2abd0 74 65 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  te an SQL statem
2abe0 65 6e 74 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ent, it must fir
2abf0 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
2ac00 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
2ac10 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
2ac20 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
2ac30 75 74 69 6e 65 73 2e 20 20 4f 72 2c 20 69 6e 20  utines.  Or, in 
2ac40 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
2ac50 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
2ac60 72 65 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 20  re constructors 
2ac70 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  for the [prepare
2ac80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
2ac90 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ect..**.** The p
2aca0 72 65 66 65 72 72 65 64 20 72 6f 75 74 69 6e 65  referred routine
2acb0 20 74 6f 20 75 73 65 20 69 73 20 5b 73 71 6c 69   to use is [sqli
2acc0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2acd0 5d 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  ].  The.** [sqli
2ace0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 69  te3_prepare()] i
2acf0 6e 74 65 72 66 61 63 65 20 69 73 20 6c 65 67 61  nterface is lega
2ad00 63 79 20 61 6e 64 20 73 68 6f 75 6c 64 20 62 65  cy and should be
2ad10 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 20 5b 73 71   avoided..** [sq
2ad20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2ad30 28 29 5d 20 68 61 73 20 61 6e 20 65 78 74 72 61  ()] has an extra
2ad40 20 22 70 72 65 70 46 6c 61 67 73 22 20 6f 70 74   "prepFlags" opt
2ad50 69 6f 6e 20 74 68 61 74 20 69 73 20 75 73 65 64  ion that is used
2ad60 0a 2a 2a 20 66 6f 72 20 73 70 65 63 69 61 6c 20  .** for special 
2ad70 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
2ad80 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 55  The use of the U
2ad90 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65 73 20  TF-8 interfaces 
2ada0 69 73 20 70 72 65 66 65 72 72 65 64 2c 20 61 73  is preferred, as
2adb0 20 53 51 4c 69 74 65 20 63 75 72 72 65 6e 74 6c   SQLite currentl
2adc0 79 0a 2a 2a 20 64 6f 65 73 20 61 6c 6c 20 70 61  y.** does all pa
2add0 72 73 69 6e 67 20 75 73 69 6e 67 20 55 54 46 2d  rsing using UTF-
2ade0 38 2e 20 20 54 68 65 20 55 54 46 2d 31 36 20 69  8.  The UTF-16 i
2adf0 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
2ae00 6f 76 69 64 65 64 0a 2a 2a 20 61 73 20 61 20 63  ovided.** as a c
2ae10 6f 6e 76 65 6e 69 65 6e 63 65 2e 20 20 54 68 65  onvenience.  The
2ae20 20 55 54 46 2d 31 36 20 69 6e 74 65 72 66 61 63   UTF-16 interfac
2ae30 65 73 20 77 6f 72 6b 20 62 79 20 63 6f 6e 76 65  es work by conve
2ae40 72 74 69 6e 67 20 74 68 65 0a 2a 2a 20 69 6e 70  rting the.** inp
2ae50 75 74 20 74 65 78 74 20 69 6e 74 6f 20 55 54 46  ut text into UTF
2ae60 2d 38 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 69 6e  -8, then invokin
2ae70 67 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  g the correspond
2ae80 69 6e 67 20 55 54 46 2d 38 20 69 6e 74 65 72 66  ing UTF-8 interf
2ae90 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ace..**.** The f
2aea0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
2aeb0 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
2aec0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2aed0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
2aee0 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
2aef0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
2af00 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
2af10 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
2af20 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
2af30 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
2af40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2af50 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
2af60 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
2af70 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
2af80 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
2af90 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
2afa0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
2afb0 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
2afc0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
2afd0 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
2afe0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2aff0 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  , sqlite3_prepar
2b000 65 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73  e_v2(),.** and s
2b010 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2b020 33 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  3().** interface
2b030 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64  s use UTF-8, and
2b040 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2b050 31 36 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72  16(), sqlite3_pr
2b060 65 70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a 2a  epare16_v2(),.**
2b070 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2b080 70 61 72 65 31 36 5f 76 33 28 29 20 75 73 65 20  pare16_v3() use 
2b090 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49  UTF-16..**.** ^I
2b0a0 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
2b0b0 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65  ment is negative
2b0c0 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
2b0d0 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
2b0e0 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
2b0f0 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74  inator. ^If nByt
2b100 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74  e is positive, t
2b110 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a  hen it is the.**
2b120 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2b130 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
2b140 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a    ^If nByte is z
2b150 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65  ero, then no pre
2b160 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2b170 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e  nt is generated.
2b180 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65  .** If the calle
2b190 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65  r knows that the
2b1a0 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67   supplied string
2b1b0 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74   is nul-terminat
2b1c0 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72  ed, then.** ther
2b1d0 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72  e is a small per
2b1e0 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61  formance advanta
2b1f0 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e  ge to passing an
2b200 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
2b210 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20   that.** is the 
2b220 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2b230 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
2b240 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
2b250 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
2b260 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
2b270 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20  * ^If pzTail is 
2b280 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70  not NULL then *p
2b290 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
2b2a0 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
2b2b0 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74  rst byte.** past
2b2c0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
2b2d0 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
2b2e0 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
2b2f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
2b300 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65  y.** compile the
2b310 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74   first statement
2b320 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
2b330 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
2b340 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74  nting to.** what
2b350 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69   remains uncompi
2b360 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53  led..**.** ^*ppS
2b370 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  tmt is left poin
2b380 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c  ting to a compil
2b390 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed [prepared sta
2b3a0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e  tement] that can
2b3b0 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
2b3c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
2b3d0 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  tep()].  ^If the
2b3e0 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
2b3f0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
2b400 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20  * to NULL.  ^If 
2b410 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
2b420 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28  ontains no SQL (
2b430 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
2b440 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69  an empty.** stri
2b450 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
2b460 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
2b470 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
2b480 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
2b490 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
2b4a0 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
2b4b0 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
2b4c0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
2b4d0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2b4e0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
2b4f0 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
2b500 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70  d with it..** pp
2b510 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20  Stmt may not be 
2b520 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20  NULL..**.** ^On 
2b530 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c  success, the sql
2b540 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66  ite3_prepare() f
2b550 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65  amily of routine
2b560 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
2b570 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69  _OK];.** otherwi
2b580 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
2b590 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
2b5a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2b5b0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2c 20  3_prepare_v2(), 
2b5c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2b5d0 76 33 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72  v3(), sqlite3_pr
2b5e0 65 70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a 2a  epare16_v2(),.**
2b5f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2b600 70 61 72 65 31 36 5f 76 33 28 29 20 69 6e 74 65  pare16_v3() inte
2b610 72 66 61 63 65 73 20 61 72 65 20 72 65 63 6f 6d  rfaces are recom
2b620 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e  mended for all n
2b630 65 77 20 70 72 6f 67 72 61 6d 73 2e 0a 2a 2a 20  ew programs..** 
2b640 54 68 65 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  The older interf
2b650 61 63 65 73 20 28 73 71 6c 69 74 65 33 5f 70 72  aces (sqlite3_pr
2b660 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69  epare() and sqli
2b670 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 29  te3_prepare16())
2b680 0a 2a 2a 20 61 72 65 20 72 65 74 61 69 6e 65 64  .** are retained
2b690 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
2b6a0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
2b6b0 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
2b6c0 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
2b6d0 49 6e 20 74 68 65 20 22 76 58 22 20 69 6e 74 65  In the "vX" inte
2b6e0 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
2b6f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
2b700 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
2b710 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
2b720 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
2b730 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
2b740 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
2b750 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
2b760 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
2b770 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
2b780 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
2b790 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
2b7a0 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
2b7b0 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
2b7c0 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
2b7d0 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
2b7e0 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
2b7f0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
2b800 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
2b810 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
2b820 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
2b830 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
2b840 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
2b850 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
2b860 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
2b870 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
2b880 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53  n. As many as [S
2b890 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41  QLITE_MAX_SCHEMA
2b8a0 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69  _RETRY].** retri
2b8b0 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65  es will occur be
2b8c0 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65  fore sqlite3_ste
2b8d0 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64  p() gives up and
2b8e0 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f   returns an erro
2b8f0 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  r..** </li>.**.*
2b900 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
2b910 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
2b920 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2b930 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
2b940 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
2b950 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
2b960 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
2b970 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
2b980 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
2b990 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
2b9a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2b9b0 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
2b9c0 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
2b9d0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
2b9e0 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
2b9f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
2ba00 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
2ba10 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
2ba20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
2ba30 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
2ba40 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
2ba50 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
2ba60 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
2ba70 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
2ba80 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
2ba90 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
2baa0 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
2bab0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
2bac0 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
2bad0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
2bae0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
2baf0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
2bb00 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
2bb10 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
2bb20 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
2bb30 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
2bb40 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
2bb50 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
2bb60 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
2bb70 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
2bb80 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
2bb90 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
2bba0 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
2bbb0 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
2bbc0 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
2bbd0 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
2bbe0 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
2bbf0 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
2bc00 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
2bc10 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
2bc20 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
2bc30 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
2bc40 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
2bc50 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
2bc60 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
2bc70 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
2bc80 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
2bc90 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
2bca0 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
2bcb0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
2bcc0 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
2bcd0 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
2bce0 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
2bcf0 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
2bd00 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
2bd10 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
2bd20 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
2bd30 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
2bd40 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
2bd50 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
2bd60 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
2bd70 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 70  * </li>.**.** <p
2bd80 3e 5e 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  >^sqlite3_prepar
2bd90 65 5f 76 33 28 29 20 64 69 66 66 65 72 73 20 66  e_v3() differs f
2bda0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 70 72 65 70  rom sqlite3_prep
2bdb0 61 72 65 5f 76 32 28 29 20 6f 6e 6c 79 20 69 6e  are_v2() only in
2bdc0 20 68 61 76 69 6e 67 0a 2a 2a 20 74 68 65 20 65   having.** the e
2bdd0 78 74 72 61 20 70 72 65 70 46 6c 61 67 73 20 70  xtra prepFlags p
2bde0 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63 68 20  arameter, which 
2bdf0 69 73 20 61 20 62 69 74 20 61 72 72 61 79 20 63  is a bit array c
2be00 6f 6e 73 69 73 74 69 6e 67 20 6f 66 20 7a 65 72  onsisting of zer
2be10 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20  o or.** more of 
2be20 74 68 65 20 5b 53 51 4c 49 54 45 5f 50 52 45 50  the [SQLITE_PREP
2be30 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 7c 53  ARE_PERSISTENT|S
2be40 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 2a 5d  QLITE_PREPARE_*]
2be50 20 66 6c 61 67 73 2e 20 20 5e 54 68 65 0a 2a 2a   flags.  ^The.**
2be60 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2be70 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
2be80 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 74 68  works exactly th
2be90 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c  e same as.** sql
2bea0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2beb0 29 20 77 69 74 68 20 61 20 7a 65 72 6f 20 70 72  ) with a zero pr
2bec0 65 70 46 6c 61 67 73 20 70 61 72 61 6d 65 74 65  epFlags paramete
2bed0 72 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69  r..** </ol>.*/.i
2bee0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2bef0 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
2bf00 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2bf10 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2bf20 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2bf30 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2bf40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2bf50 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
2bf60 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2bf70 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2bf80 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2bf90 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2bfa0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2bfb0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2bfc0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2bfd0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2bfe0 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
2bff0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2c000 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2c010 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2c020 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
2c030 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
2c040 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2c050 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2c060 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2c070 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
2c080 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
2c090 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
2c0a0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2c0b0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2c0c0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2c0d0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2c0e0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
2c0f0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2c100 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2c110 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2c120 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
2c130 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2c140 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2c150 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2c160 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
2c170 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 0a  te3_prepare_v3(.
2c180 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2c190 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2c1a0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2c1b0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
2c1c0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2c1d0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2c1e0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
2c1f0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2c200 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2c210 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2c220 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2c230 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65  unsigned int pre
2c240 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20  pFlags, /* Zero 
2c250 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50  or more SQLITE_P
2c260 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f  REPARE_ flags */
2c270 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2c280 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2c290 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2c2a0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2c2b0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
2c2c0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2c2d0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2c2e0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2c2f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
2c300 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
2c310 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2c320 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2c330 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2c340 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
2c350 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2c360 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
2c370 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2c380 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2c390 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2c3a0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2c3b0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2c3c0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2c3d0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2c3e0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2c3f0 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
2c400 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2c410 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2c420 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2c430 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
2c440 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2c450 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2c460 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2c470 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2c480 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
2c490 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2c4a0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2c4b0 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
2c4c0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2c4d0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2c4e0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2c4f0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2c500 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2c510 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2c520 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2c530 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2c540 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
2c550 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2c560 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2c570 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2c580 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
2c590 61 72 65 31 36 5f 76 33 28 0a 20 20 73 71 6c 69  are16_v3(.  sqli
2c5a0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2c5b0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2c5c0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2c5d0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
2c5e0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
2c5f0 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
2c600 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2c610 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2c620 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2c630 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2c640 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67  ytes. */.  unsig
2c650 6e 65 64 20 69 6e 74 20 70 72 65 70 46 61 6c 67  ned int prepFalg
2c660 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f  s, /* Zero or mo
2c670 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52  re SQLITE_PREPAR
2c680 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71  E_ flags */.  sq
2c690 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2c6a0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2c6b0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2c6c0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2c6d0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2c6e0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2c6f0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2c700 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   zSql */.);../*.
2c710 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74  ** CAPI3REF: Ret
2c720 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e  rieving Statemen
2c730 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t SQL.** METHOD:
2c740 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2c750 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2c760 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63  _sql(P) interfac
2c770 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2c780 74 65 72 20 74 6f 20 61 20 63 6f 70 79 20 6f 66  ter to a copy of
2c790 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20 53 51   the UTF-8.** SQ
2c7a0 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63  L text used to c
2c7b0 72 65 61 74 65 20 5b 70 72 65 70 61 72 65 64 20  reate [prepared 
2c7c0 73 74 61 74 65 6d 65 6e 74 5d 20 50 20 69 66 20  statement] P if 
2c7d0 50 20 77 61 73 0a 2a 2a 20 63 72 65 61 74 65 64  P was.** created
2c7e0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
2c7f0 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
2c800 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2c810 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2c820 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c  prepare16_v2()],
2c830 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2c840 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a  pare16_v3()]..**
2c850 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
2c860 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 20 69 6e  panded_sql(P) in
2c870 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2c880 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55  a pointer to a U
2c890 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63  TF-8.** string c
2c8a0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 53 51  ontaining the SQ
2c8b0 4c 20 74 65 78 74 20 6f 66 20 70 72 65 70 61 72  L text of prepar
2c8c0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 77  ed statement P w
2c8d0 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70 61  ith.** [bound pa
2c8e0 72 61 6d 65 74 65 72 73 5d 20 65 78 70 61 6e 64  rameters] expand
2c8f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
2c900 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 20 70 72  example, if a pr
2c910 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c920 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e   is created usin
2c930 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65 78  g the SQL.** tex
2c940 74 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a  t "SELECT $abc,:
2c950 78 79 7a 22 20 61 6e 64 20 69 66 20 70 61 72 61  xyz" and if para
2c960 6d 65 74 65 72 20 24 61 62 63 20 69 73 20 62 6f  meter $abc is bo
2c970 75 6e 64 20 74 6f 20 69 6e 74 65 67 65 72 20 32  und to integer 2
2c980 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61 6d  345.** and param
2c990 65 74 65 72 20 3a 78 79 7a 20 69 73 20 75 6e 62  eter :xyz is unb
2c9a0 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69 74  ound, then sqlit
2c9b0 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72 65  e3_sql() will re
2c9c0 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69 67  turn.** the orig
2c9d0 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20 22 53 45  inal string, "SE
2c9e0 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20  LECT $abc,:xyz" 
2c9f0 62 75 74 20 73 71 6c 69 74 65 33 5f 65 78 70 61  but sqlite3_expa
2ca00 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77 69  nded_sql().** wi
2ca10 6c 6c 20 72 65 74 75 72 6e 20 22 53 45 4c 45 43  ll return "SELEC
2ca20 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a  T 2345,NULL".)^.
2ca30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2ca40 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2ca50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2ca60 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75  rns NULL if insu
2ca70 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 0a  fficient memory.
2ca80 2a 2a 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  ** is available 
2ca90 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
2caa0 6c 74 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65  lt, or if the re
2cab0 73 75 6c 74 20 77 6f 75 6c 64 20 65 78 63 65 65  sult would excee
2cac0 64 20 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61 78  d the.** the max
2cad0 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e 67  imum string leng
2cae0 74 68 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  th determined by
2caf0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49 4d   the [SQLITE_LIM
2cb00 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a  IT_LENGTH]..**.*
2cb10 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 54  * ^The [SQLITE_T
2cb20 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d  RACE_SIZE_LIMIT]
2cb30 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2cb40 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65 20  tion limits the 
2cb50 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64  size of.** bound
2cb60 20 70 61 72 61 6d 65 74 65 72 20 65 78 70 61 6e   parameter expan
2cb70 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53 51  sions.  ^The [SQ
2cb80 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45 5d  LITE_OMIT_TRACE]
2cb90 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
2cba0 20 6f 70 74 69 6f 6e 20 63 61 75 73 65 73 20 73   option causes s
2cbb0 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2cbc0 73 71 6c 28 29 20 74 6f 20 61 6c 77 61 79 73 20  sql() to always 
2cbd0 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a  return NULL..**.
2cbe0 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72  ** ^The string r
2cbf0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2cc00 65 33 5f 73 71 6c 28 50 29 20 69 73 20 6d 61 6e  e3_sql(P) is man
2cc10 61 67 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  aged by SQLite a
2cc20 6e 64 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74  nd is.** automat
2cc30 69 63 61 6c 6c 79 20 66 72 65 65 64 20 77 68 65  ically freed whe
2cc40 6e 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  n the prepared s
2cc50 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61  tatement is fina
2cc60 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  lized..** ^The s
2cc70 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62  tring returned b
2cc80 79 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  y sqlite3_expand
2cc90 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e 20 74 68  ed_sql(P), on th
2cca0 65 20 6f 74 68 65 72 20 68 61 6e 64 2c 0a 2a 2a  e other hand,.**
2ccb0 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f   is obtained fro
2ccc0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2ccd0 63 28 29 5d 20 61 6e 64 20 6d 75 73 74 20 62 65  c()] and must be
2cce0 20 66 72 65 65 20 62 79 20 74 68 65 20 61 70 70   free by the app
2ccf0 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62 79 20 70  lication.** by p
2cd00 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
2cd10 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
2cd20 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
2cd30 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
2cd40 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2cd50 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 78  char *sqlite3_ex
2cd60 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69 74  panded_sql(sqlit
2cd70 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2cd80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2cd90 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
2cda0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
2cdb0 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
2cdc0 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ase.** METHOD: s
2cdd0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2cde0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2cdf0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20  tmt_readonly(X) 
2ce00 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2ce10 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
2ce20 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ) if.** and only
2ce30 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   if the [prepare
2ce40 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d  d statement] X m
2ce50 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63  akes no direct c
2ce60 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65  hanges to.** the
2ce70 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2ce80 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a  database file..*
2ce90 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  *.** Note that [
2cea0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2ceb0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2cec0 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61  s] or.** [virtua
2ced0 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20  l tables] might 
2cee0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2cef0 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61  ase indirectly a
2cf00 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e  s a side effect.
2cf10 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d    .** ^(For exam
2cf20 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69  ple, if an appli
2cf30 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61  cation defines a
2cf40 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28   function "eval(
2cf50 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c  )" that .** call
2cf60 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  s [sqlite3_exec(
2cf70 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c  )], then the fol
2cf80 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65  lowing SQL state
2cf90 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68  ment would.** ch
2cfa0 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
2cfb0 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73  e file through s
2cfc0 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a  ide-effects:.**.
2cfd0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
2cfe0 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43  pre>.**    SELEC
2cff0 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46  T eval('DELETE F
2d000 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32  ROM t1') FROM t2
2d010 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
2d020 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
2d030 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b  ut because the [
2d040 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2d050 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  t does not chang
2d060 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
2d070 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c  ile.** directly,
2d080 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2d090 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73  adonly() would s
2d0a0 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65  till return true
2d0b0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73  .)^.**.** ^Trans
2d0c0 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73  action control s
2d0d0 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61  tatements such a
2d0e0 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d  s [BEGIN], [COMM
2d0f0 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c  IT], [ROLLBACK],
2d100 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c  .** [SAVEPOINT],
2d110 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63   and [RELEASE] c
2d120 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ause sqlite3_stm
2d130 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
2d140 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20  return true,.** 
2d150 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d  since the statem
2d160 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20  ents themselves 
2d170 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20  do not actually 
2d180 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
2d190 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65  ase but.** rathe
2d1a0 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74  r they control t
2d1b0 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65  he timing of whe
2d1c0 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e  n other statemen
2d1d0 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a  ts modify the .*
2d1e0 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68  * database.  ^Th
2d1f0 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b  e [ATTACH] and [
2d200 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e  DETACH] statemen
2d210 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a  ts also cause.**
2d220 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2d230 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
2d240 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77  rn true since, w
2d250 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65  hile those state
2d260 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20  ments.** change 
2d270 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
2d280 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  n of a database 
2d290 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79  connection, they
2d2a0 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a   do not make .**
2d2b0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
2d2c0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
2d2d0 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e  atabase files on
2d2e0 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65 20 73   disk..** ^The s
2d2f0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2d300 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66 61 63 65  only() interface
2d310 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 66 6f   returns true fo
2d320 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e 63 65 0a  r [BEGIN] since.
2d330 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65 72 65 6c  ** [BEGIN] merel
2d340 79 20 73 65 74 73 20 69 6e 74 65 72 6e 61 6c 20  y sets internal 
2d350 66 6c 61 67 73 2c 20 62 75 74 20 74 68 65 20 5b  flags, but the [
2d360 42 45 47 49 4e 7c 42 45 47 49 4e 20 49 4d 4d 45  BEGIN|BEGIN IMME
2d370 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 42  DIATE] and.** [B
2d380 45 47 49 4e 7c 42 45 47 49 4e 20 45 58 43 4c 55  EGIN|BEGIN EXCLU
2d390 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64 73 20 64  SIVE] commands d
2d3a0 6f 20 74 6f 75 63 68 20 74 68 65 20 64 61 74 61  o touch the data
2d3b0 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a 2a 20 73  base and so.** s
2d3c0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2d3d0 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e 73 20 66  only() returns f
2d3e0 61 6c 73 65 20 66 6f 72 20 74 68 6f 73 65 20 63  alse for those c
2d3f0 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20  ommands..*/.int 
2d400 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2d410 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74  donly(sqlite3_st
2d420 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2d430 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
2d440 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70  ermine If A Prep
2d450 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48  ared Statement H
2d460 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a  as Been Reset.**
2d470 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2d480 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2d490 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
2d4a0 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20  sy(S) interface 
2d4b0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
2d4c0 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a  n-zero) if the.*
2d4d0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2d4e0 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65  ement] S has bee
2d4f0 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61  n stepped at lea
2d500 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a  st once using .*
2d510 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2d520 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65 69 74  S)] but has neit
2d530 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c  her run to compl
2d540 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a  etion (returned.
2d550 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
2d560 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73   from [sqlite3_s
2d570 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20  tep(S)]) nor.** 
2d580 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67  been reset using
2d590 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2d5a0 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  S)].  ^The sqlit
2d5b0 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a  e3_stmt_busy(S).
2d5c0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
2d5d0 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20  urns false if S 
2d5e0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2d5f0 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20  r.  If S is not 
2d600 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74  a .** NULL point
2d610 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  er and is not a 
2d620 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
2d630 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  id [prepared sta
2d640 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
2d650 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  t, then the beha
2d660 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
2d670 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
2d680 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a  ndesirable..**.*
2d690 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
2d6a0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20   can be used in 
2d6b0 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c  combination [sql
2d6c0 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29  ite3_next_stmt()
2d6d0 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61  ].** to locate a
2d6e0 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ll prepared stat
2d6f0 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65  ements associate
2d700 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  d with a databas
2d710 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  e .** connection
2d720 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65   that are in nee
2d730 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74  d of being reset
2d740 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75  .  This can be u
2d750 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d  sed,.** for exam
2d760 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74  ple, in diagnost
2d770 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73  ic routines to s
2d780 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72  earch for prepar
2d790 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ed .** statement
2d7a0 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69  s that are holdi
2d7b0 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
2d7c0 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71   open..*/.int sq
2d7d0 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
2d7e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2d7f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d800 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
2d810 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
2d820 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
2d830 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2d840 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
2d850 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2d860 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
2d870 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
2d880 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
2d890 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
2d8a0 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
2d8b0 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
2d8c0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
2d8d0 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
2d8e0 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
2d8f0 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
2d900 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
2d910 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
2d920 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2d930 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
2d940 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
2d950 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
2d960 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
2d970 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
2d980 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2d990 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
2d9a0 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
2d9b0 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
2d9c0 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
2d9d0 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
2d9e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2d9f0 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
2da00 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
2da10 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
2da20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
2da30 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2da40 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
2da50 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
2da60 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
2da70 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
2da80 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
2da90 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
2daa0 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
2dab0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2dac0 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  alue.  The.** [s
2dad0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
2dae0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61  ()] interface ca
2daf0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e  n be used to con
2db00 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a  struct a new .**
2db10 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
2db20 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e  e3_value from an
2db30 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
2db40 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  ite3_value..**.*
2db50 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f  * The terms "pro
2db60 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70  tected" and "unp
2db70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20  rotected" refer 
2db80 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  to whether or no
2db90 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20  t.** a mutex is 
2dba0 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e  held.  An intern
2dbb0 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  al mutex is held
2dbc0 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64   for a protected
2dbd0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2dbe0 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20  e object but no 
2dbf0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
2dc00 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
2dc10 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2dc20 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51  e object.  If SQ
2dc30 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
2dc40 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68   to be single-th
2dc50 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20  readed.** (with 
2dc60 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
2dc70 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b  FE=0] and with [
2dc80 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2dc90 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20  fe()] returning 
2dca0 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69  0).** or if SQLi
2dcb0 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65  te is run in one
2dcc0 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65   of reduced mute
2dcd0 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c  x modes .** [SQL
2dce0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
2dcf0 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c  ETHREAD] or [SQL
2dd00 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
2dd10 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20  THREAD].** then 
2dd20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74  there is no dist
2dd30 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
2dd40 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
2dd50 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2dd60 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2dd70 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20  ts and they can 
2dd80 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61  be used intercha
2dd90 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65  ngeably.  Howeve
2dda0 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75  r,.** for maximu
2ddb0 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69  m code portabili
2ddc0 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ty it is recomme
2ddd0 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
2dde0 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20  ations.** still 
2ddf0 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
2de00 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
2de10 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
2de20 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2de30 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
2de40 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74  even when not st
2de50 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e  rictly required.
2de60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2de70 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2de80 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
2de90 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
2dea0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
2deb0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61  ementation of [a
2dec0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2ded0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2dee0 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e  ] are protected.
2def0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2df00 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65  _value object re
2df10 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
2df20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2df30 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65  ue()] is unprote
2df40 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65  cted..** Unprote
2df50 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2df60 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f  ue objects may o
2df70 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
2df80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2df90 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ult_value()] and
2dfa0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
2dfb0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  alue()]..** The 
2dfc0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2dfd0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61  lob | sqlite3_va
2dfe0 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69  lue_type()] fami
2dff0 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  ly of.** interfa
2e000 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74  ces require prot
2e010 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e020 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a  lue objects..*/.
2e030 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2e040 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 73 71 6c  qlite3_value sql
2e050 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
2e060 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
2e070 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
2e080 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
2e090 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
2e0a0 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
2e0b0 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
2e0c0 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
2e0d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2e0e0 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e  object.  ^A poin
2e0f0 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
2e100 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
2e110 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
2e120 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
2e130 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2e140 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2e150 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
2e160 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2e170 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
2e180 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
2e190 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
2e1a0 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
2e1b0 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
2e1c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
2e1d0 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
2e1e0 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
2e1f0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2e200 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
2e210 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
2e220 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
2e230 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
2e240 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
2e250 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
2e260 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
2e270 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
2e280 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2e290 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
2e2a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
2e2b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e2c0 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
2e2d0 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
2e2e0 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52  ements.** KEYWOR
2e2f0 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  DS: {host parame
2e300 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ter} {host param
2e310 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72  eters} {host par
2e320 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20  ameter name}.** 
2e330 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70  KEYWORDS: {SQL p
2e340 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70  arameter} {SQL p
2e350 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61  arameters} {para
2e360 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a  meter binding}.*
2e370 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2e380 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49  3_stmt.**.** ^(I
2e390 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
2e3a0 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74  ent text input t
2e3b0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
2e3c0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
2e3d0 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
2e3e0 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
2e3f0 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72  placed by a [par
2e400 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74  ameter] that mat
2e410 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c  ches one of foll
2e420 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74  owing.** templat
2e430 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
2e440 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
2e450 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
2e460 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
2e470 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
2e480 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
2e490 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65   In the template
2e4a0 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70  s above, NNN rep
2e4b0 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67  resents an integ
2e4c0 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
2e4d0 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74  nd VVV represent
2e4e0 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69  s an alphanumeri
2e4f0 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20  c identifier.)^ 
2e500 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20   ^The values of 
2e510 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
2e520 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
2e530 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
2e540 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
2e550 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
2e560 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
2e570 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2e580 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
2e590 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
2e5a0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2e5b0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
2e5c0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2e5d0 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
2e5e0 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
2e5f0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
2e600 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
2e610 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
2e620 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2e630 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
2e640 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
2e650 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2e660 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
2e670 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
2e680 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
2e690 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51  ^The leftmost SQ
2e6a0 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
2e6b0 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
2e6c0 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  ^When the same n
2e6d0 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
2e6e0 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
2e6f0 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
2e700 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
2e710 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
2e720 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
2e730 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
2e740 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
2e750 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f  ** ^The index fo
2e760 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
2e770 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
2e780 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
2e790 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2e7a0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2e7b0 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
2e7c0 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a  .  ^The index.**
2e7d0 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
2e7e0 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
2e7f0 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e  lue of NNN..** ^
2e800 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
2e810 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
2e820 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
2e830 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
2e840 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
2e850 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
2e860 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
2e870 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
2e880 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
2e890 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
2e8a0 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
2e8b0 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
2e8c0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
2e8d0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2e8e0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
2e8f0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2e900 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71  ext16().** or sq
2e910 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2e920 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
2e930 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ter then the fou
2e940 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rth parameter.**
2e950 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20   is ignored and 
2e960 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69  the end result i
2e970 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71  s the same as sq
2e980 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
2e990 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  )..**.** ^(In th
2e9a0 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
2e9b0 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
2e9c0 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
2e9d0 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
2e9e0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2e9f0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
2ea00 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
2ea10 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
2ea20 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
2ea30 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
2ea40 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
2ea50 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
2ea60 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68  ers.)^.** ^If th
2ea70 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2ea80 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2ea90 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
2eaa0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2eab0 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  ().** is negativ
2eac0 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67  e, then the leng
2ead0 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
2eae0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
2eaf0 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
2eb00 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
2eb10 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49  terminator..** I
2eb20 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2eb30 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2eb40 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
2eb50 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a   negative, then.
2eb60 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ** the behavior 
2eb70 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2eb80 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69   If a non-negati
2eb90 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ve fourth parame
2eba0 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20  ter is provided 
2ebb0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2ebc0 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  text().** or sql
2ebd0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2ebe0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
2ebf0 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e  nd_text64() then
2ec00 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74  .** that paramet
2ec10 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62  er must be the b
2ec20 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68  yte offset.** wh
2ec30 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d  ere the NUL term
2ec40 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63  inator would occ
2ec50 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20  ur assuming the 
2ec60 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a  string were NUL.
2ec70 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ** terminated.  
2ec80 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61  If any NUL chara
2ec90 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62  cters occur at b
2eca0 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73  yte offsets less
2ecb0 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61   than .** the va
2ecc0 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74  lue of the fourt
2ecd0 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e  h parameter then
2ece0 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
2ecf0 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c  tring value will
2ed00 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  .** contain embe
2ed10 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20  dded NULs.  The 
2ed20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73  result of expres
2ed30 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20  sions involving 
2ed40 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20  strings.** with 
2ed50 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73  embedded NULs is
2ed60 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2ed70 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
2ed80 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f  ument to the BLO
2ed90 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e  B and string bin
2eda0 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a  ding interfaces.
2edb0 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 74  ** is a destruct
2edc0 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f  or used to dispo
2edd0 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
2ede0 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65  r.** string afte
2edf0 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e  r SQLite has fin
2ee00 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20  ished with it.  
2ee10 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
2ee20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20  is called.** to 
2ee30 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
2ee40 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76  LOB or string ev
2ee50 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  en if the call t
2ee60 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73  o bind API fails
2ee70 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
2ee80 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  th argument is.*
2ee90 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61  * the special va
2eea0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
2eeb0 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  IC], then SQLite
2eec0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
2eed0 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
2eee0 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
2eef0 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
2ef00 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
2ef10 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a   to be freed..**
2ef20 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
2ef30 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
2ef40 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
2ef50 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
2ef60 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
2ef70 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
2ef80 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
2ef90 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
2efa0 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
2efb0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2efc0 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
2efd0 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 72  ** ^The sixth ar
2efe0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
2eff0 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
2f000 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a  must be one of.*
2f010 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  * [SQLITE_UTF8],
2f020 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c   [SQLITE_UTF16],
2f030 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
2f040 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ], or [SQLITE_UT
2f050 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65  F16LE].** to spe
2f060 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e  cify the encodin
2f070 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e  g of the text in
2f080 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
2f090 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65  eter.  If.** the
2f0a0 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20   sixth argument 
2f0b0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2f0c0 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20  text64() is not 
2f0d0 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c  one of the.** al
2f0e0 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f  lowed values sho
2f0f0 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20  wn above, or if 
2f100 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
2f110 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a  g is different.*
2f120 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64  * from the encod
2f130 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 79  ing specified by
2f140 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d   the sixth param
2f150 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62  eter, then the b
2f160 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e  ehavior.** is un
2f170 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2f180 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2f190 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74  _zeroblob() rout
2f1a0 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42  ine binds a BLOB
2f1b0 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61   of length N tha
2f1c0 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77  t.** is filled w
2f1d0 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20  ith zeroes.  ^A 
2f1e0 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
2f1f0 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
2f200 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
2f210 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
2f220 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69  ld its size) whi
2f230 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
2f240 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
2f250 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
2f260 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
2f270 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
2f280 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
2f290 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
2f2a0 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a   written using.*
2f2b0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
2f2c0 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
2f2d0 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  al BLOB I/O] rou
2f2e0 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67  tines..** ^A neg
2f2f0 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20  ative value for 
2f300 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73  the zeroblob res
2f310 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c  ults in a zero-l
2f320 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a  ength BLOB..**.*
2f330 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2f340 69 6e 64 5f 70 6f 69 6e 74 65 72 28 53 2c 49 2c  ind_pointer(S,I,
2f350 50 2c 54 29 20 72 6f 75 74 69 6e 65 20 63 61 75  P,T) routine cau
2f360 73 65 73 20 74 68 65 20 49 2d 74 68 20 70 61 72  ses the I-th par
2f370 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 5b 70 72  ameter in.** [pr
2f380 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f390 5d 20 53 20 74 6f 20 68 61 76 65 20 61 6e 20 53  ] S to have an S
2f3a0 51 4c 20 76 61 6c 75 65 20 6f 66 20 4e 55 4c 4c  QL value of NULL
2f3b0 2c 20 62 75 74 20 74 6f 20 61 6c 73 6f 20 62 65  , but to also be
2f3c0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
2f3d0 69 74 68 20 74 68 65 20 70 6f 69 6e 74 65 72 20  ith the pointer 
2f3e0 50 20 6f 66 20 74 79 70 65 20 54 2e 0a 2a 2a 20  P of type T..** 
2f3f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2f400 64 5f 70 6f 69 6e 74 65 72 28 29 20 72 6f 75 74  d_pointer() rout
2f410 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ine can be used 
2f420 74 6f 20 70 61 73 73 0a 2a 2a 20 68 6f 73 74 2d  to pass.** host-
2f430 6c 61 6e 67 75 61 67 65 20 70 6f 69 6e 74 65 72  language pointer
2f440 73 20 69 6e 74 6f 20 5b 61 70 70 6c 69 63 61 74  s into [applicat
2f450 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2f460 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 5e  functions]..** ^
2f470 41 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  A parameter that
2f480 20 69 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20   is initialized 
2f490 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
2f4a0 69 6e 64 5f 70 6f 69 6e 74 65 72 28 29 5d 20 61  ind_pointer()] a
2f4b0 70 70 65 61 72 73 0a 2a 2a 20 74 6f 20 62 65 20  ppears.** to be 
2f4c0 61 6e 20 6f 72 64 69 6e 61 72 79 20 53 51 4c 20  an ordinary SQL 
2f4d0 4e 55 4c 4c 20 76 61 6c 75 65 20 74 6f 20 65 76  NULL value to ev
2f4e0 65 72 79 74 68 69 6e 67 20 6f 74 68 65 72 20 74  erything other t
2f4f0 68 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  han.** [sqlite3_
2f500 76 61 6c 75 65 5f 70 6f 69 6e 74 65 72 28 29 5d  value_pointer()]
2f510 2e 20 20 54 68 65 20 54 20 70 61 72 61 6d 65 74  .  The T paramet
2f520 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 73  er should be a s
2f530 74 61 74 69 63 20 73 74 72 69 6e 67 2e 0a 2a 2a  tatic string..**
2f540 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74  .** ^If any of t
2f550 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2f560 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  *() routines are
2f570 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
2f580 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66  ULL pointer.** f
2f590 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
2f5a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77   statement] or w
2f5b0 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73  ith a prepared s
2f5c0 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69  tatement for whi
2f5d0 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  ch.** [sqlite3_s
2f5e0 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20  tep()] has been 
2f5f0 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65  called more rece
2f600 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74  ntly than [sqlit
2f610 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20  e3_reset()],.** 
2f620 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69  then the call wi
2f630 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
2f640 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61  E_MISUSE].  If a
2f650 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ny sqlite3_bind_
2f660 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73  ().** routine is
2f670 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61   passed a [prepa
2f680 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2f690 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e  hat has been fin
2f6a0 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72  alized, the.** r
2f6b0 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
2f6c0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
2f6d0 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
2f6e0 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
2f6f0 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
2f700 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2f710 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55  ] routine..** ^U
2f720 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
2f730 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
2f740 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
2f750 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
2f760 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65  nd_* routines re
2f770 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2f780 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
2f790 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  n.** [error code
2f7a0 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f  ] if anything go
2f7b0 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53  es wrong..** ^[S
2f7c0 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69  QLITE_TOOBIG] mi
2f7d0 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
2f7e0 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  if the size of a
2f7f0 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a   string or BLOB.
2f800 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74  ** exceeds limit
2f810 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71  s imposed by [sq
2f820 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
2f830 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
2f840 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  H]) or.** [SQLIT
2f850 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a  E_MAX_LENGTH]..*
2f860 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
2f870 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
2f880 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
2f890 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
2f8a0 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
2f8b0 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
2f8c0 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
2f8d0 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
2f8e0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2f8f0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2f900 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
2f910 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2f920 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
2f930 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
2f940 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2f950 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
2f960 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
2f970 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2f980 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2f990 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
2f9a0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
2f9b0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73  e3_bind_blob64(s
2f9c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2f9d0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
2f9e0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a  sqlite3_uint64,.
2f9f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2fa00 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28          void(*)(
2fa10 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
2fa20 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
2fa30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2fa40 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e  int, double);.in
2fa50 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
2fa60 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
2fa70 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74  , int, int);.int
2fa80 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
2fa90 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
2faa0 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
2fab0 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69  int64);.int sqli
2fac0 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71  te3_bind_null(sq
2fad0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2fae0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2faf0 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
2fb00 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74  _stmt*,int,const
2fb10 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28   char*,int,void(
2fb20 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
2fb30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2fb40 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
2fb50 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
2fb60 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
2fb70 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
2fb80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2fb90 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2fba0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
2fbb0 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  r*, sqlite3_uint
2fbc0 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
2fbd0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
2fbe0 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73  d(*)(void*), uns
2fbf0 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64  igned char encod
2fc00 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ing);.int sqlite
2fc10 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
2fc20 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2fc30 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
2fc40 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2fc50 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72  te3_bind_pointer
2fc60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2fc70 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 63 6f 6e 73  int, void*, cons
2fc80 74 20 63 68 61 72 2a 29 3b 0a 69 6e 74 20 73 71  t char*);.int sq
2fc90 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
2fca0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2fcb0 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
2fcc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2fcd0 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69  _zeroblob64(sqli
2fce0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2fcf0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b  sqlite3_uint64);
2fd00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2fd10 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20  : Number Of SQL 
2fd20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45  Parameters.** ME
2fd30 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2fd40 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  mt.**.** ^This r
2fd50 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
2fd60 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
2fd70 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61  umber of [SQL pa
2fd80 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20  rameters].** in 
2fd90 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2fda0 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72  ement].  SQL par
2fdb0 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65  ameters are toke
2fdc0 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ns of the.** for
2fdd0 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22  m "?", "?NNN", "
2fde0 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f  :AAA", "$AAA", o
2fdf0 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65  r "@AAA" that se
2fe00 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68  rve as.** placeh
2fe10 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65  olders for value
2fe20 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69  s that are [sqli
2fe30 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2fe40 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65  bound].** to the
2fe50 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61   parameters at a
2fe60 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a   later time..**.
2fe70 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
2fe80 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72  e actually retur
2fe90 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  ns the index of 
2fea0 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67  the largest (rig
2feb0 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d  htmost).** param
2fec0 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f  eter. For all fo
2fed0 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c  rms except ?NNN,
2fee0 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65   this will corre
2fef0 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20  spond to the.** 
2ff00 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65  number of unique
2ff10 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66   parameters.  If
2ff20 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
2ff30 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65  he ?NNN form are
2ff40 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20   used,.** there 
2ff50 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74  may be gaps in t
2ff60 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a  he list.)^.**.**
2ff70 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2ff80 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2ff90 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2ffa0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2ffb0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
2ffc0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2ffd0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2ffe0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
2fff0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
30000 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
30010 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
30020 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30030 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
30040 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54  Parameter.** MET
30050 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
30060 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
30070 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
30080 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e  ter_name(P,N) in
30090 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
300a0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** the name of t
300b0 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72  he N-th [SQL par
300c0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b  ameter] in the [
300d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
300e0 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20  nt] P..** ^(SQL 
300f0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
30100 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
30110 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
30120 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
30130 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
30140 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
30150 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
30160 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
30170 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
30180 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
30190 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
301a0 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
301b0 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
301c0 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
301d0 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
301e0 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72  )^.** ^Parameter
301f0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
30200 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c  " without a foll
30210 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61  owing integer ha
30220 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e  ve no name.** an
30230 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74  d are referred t
30240 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20  o as "nameless" 
30250 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61  or "anonymous pa
30260 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a  rameters"..**.**
30270 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74   ^The first host
30280 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
30290 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
302a0 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t 0..**.** ^If t
302b0 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75  he value N is ou
302c0 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
302d0 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65   the N-th parame
302e0 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
302f0 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
30300 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65   returned.  ^The
30310 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
30320 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
30330 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
30340 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
30350 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
30360 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
30370 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
30380 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
30390 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 5b  epare16()],.** [
303a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
303b0 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c  6_v2()], or [sql
303c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
303d0 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  3()]..**.** See 
303e0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
303f0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
30400 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
30410 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
30420 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
30430 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
30440 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
30450 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  dex()]..*/.const
30460 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
30470 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
30480 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
30490 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
304a0 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
304b0 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
304c0 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a  th A Given Name.
304d0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
304e0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52  e3_stmt.**.** ^R
304f0 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
30500 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
30510 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
30520 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64  me.  ^The.** ind
30530 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
30540 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
30550 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
30560 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
30570 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
30580 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
30590 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f  ind()].  ^A zero
305a0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
305b0 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70  if no matching p
305c0 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e  arameter is foun
305d0 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  d.  ^The paramet
305e0 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
305f0 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
30600 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
30610 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
30620 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
30630 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
30640 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
30650 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
30660 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
30670 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e  prepare16_v3()].
30680 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
30690 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
306a0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
306b0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
306c0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
306d0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
306e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
306f0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
30700 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
30710 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
30720 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
30730 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
30740 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
30750 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
30760 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
30770 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
30780 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ment.** METHOD: 
30790 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
307a0 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20  ** ^Contrary to 
307b0 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
307c0 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
307d0 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
307e0 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
307f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
30800 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
30810 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
30820 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65  tement]..** ^Use
30830 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
30840 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
30850 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
30860 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
30870 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
30880 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
30890 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
308a0 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
308b0 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
308c0 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   Set.** METHOD: 
308d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
308e0 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e  ** ^Return the n
308f0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
30900 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
30910 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
30920 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
30930 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 49 66 20  statement]. ^If 
30940 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
30950 75 72 6e 73 20 30 2c 20 74 68 61 74 20 6d 65 61  urns 0, that mea
30960 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70  ns the .** [prep
30970 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
30980 72 65 74 75 72 6e 73 20 6e 6f 20 64 61 74 61 20  returns no data 
30990 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
309a0 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e 48  [UPDATE])..** ^H
309b0 6f 77 65 76 65 72 2c 20 6a 75 73 74 20 62 65 63  owever, just bec
309c0 61 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e  ause this routin
309d0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69  e returns a posi
309e0 74 69 76 65 20 6e 75 6d 62 65 72 20 64 6f 65 73  tive number does
309f0 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74 68 61   not.** mean tha
30a00 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 72 6f  t one or more ro
30a10 77 73 20 6f 66 20 64 61 74 61 20 77 69 6c 6c 20  ws of data will 
30a20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 41  be returned.  ^A
30a30 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
30a40 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73  t.** will always
30a50 20 68 61 76 65 20 61 20 70 6f 73 69 74 69 76 65   have a positive
30a60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30a70 63 6f 75 6e 74 28 29 20 62 75 74 20 64 65 70 65  count() but depe
30a80 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a 20  nding on the.** 
30a90 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e  WHERE clause con
30aa0 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 65  straints and the
30ab0 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e 74 2c 20   table content, 
30ac0 69 74 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20  it might return 
30ad0 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 53  no rows..**.** S
30ae0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
30af0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a  3_data_count()].
30b00 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
30b10 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69  olumn_count(sqli
30b20 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
30b30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
30b40 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20  F: Column Names 
30b50 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
30b60 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
30b70 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
30b80 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
30b90 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73  turn the name as
30ba0 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74  signed to a part
30bb0 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  icular column.**
30bc0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
30bd0 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
30be0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68   statement.  ^Th
30bf0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
30c00 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72  _name().** inter
30c10 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
30c20 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
30c30 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
30c40 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20  8 string.** and 
30c50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
30c60 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20  ame16() returns 
30c70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
30c80 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
30c90 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  * UTF-16 string.
30ca0 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72    ^The first par
30cb0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
30cc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30cd0 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
30ce0 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43  ments the [SELEC
30cf0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54  T] statement. ^T
30d00 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
30d10 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  ter is the.** co
30d20 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54  lumn number.  ^T
30d30 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
30d40 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a  mn is number 0..
30d50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  **.** ^The retur
30d60 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ned string point
30d70 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  er is valid unti
30d80 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72  l either the [pr
30d90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30da0 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65  ].** is destroye
30db0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
30dc0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
30dd0 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
30de0 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
30df0 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
30e00 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
30e10 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
30e20 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
30e30 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
30e40 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
30e50 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
30e60 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
30e70 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
30e80 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
30e90 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
30ea0 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  **.** ^If sqlite
30eb0 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
30ec0 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
30ed0 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
30ee0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
30ef0 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
30f00 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
30f10 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
30f20 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
30f30 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
30f40 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
30f50 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
30f60 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
30f70 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
30f80 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
30f90 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
30fa0 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
30fb0 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
30fc0 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
30fd0 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
30fe0 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
30ff0 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
31000 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
31010 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
31020 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
31030 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e  the next..*/.con
31040 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
31050 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
31060 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
31070 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  N);.const void *
31080 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
31090 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
310a0 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
310b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
310c0 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
310d0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
310e0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
310f0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
31100 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
31110 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
31120 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61  determine the da
31130 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
31140 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75  nd.** table colu
31150 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f  mn that is the o
31160 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69  rigin of a parti
31170 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c  cular result col
31180 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43  umn in.** [SELEC
31190 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  T] statement..**
311a0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
311b0 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61  e database or ta
311c0 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61  ble or column ca
311d0 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  n be returned as
311e0 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46  .** either a UTF
311f0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  -8 or UTF-16 str
31200 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61  ing.  ^The _data
31210 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
31220 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
31230 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
31240 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
31250 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
31260 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
31270 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
31280 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
31290 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  olumn name..** ^
312a0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
312b0 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
312c0 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  il the [prepared
312d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
312e0 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e  estroyed.** usin
312f0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
31300 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
31310 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
31320 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
31330 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
31340 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
31350 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
31360 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
31370 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
31380 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66  til the same inf
31390 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75  ormation is requ
313a0 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69  ested.** again i
313b0 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e  n a different en
313c0 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54  coding..**.** ^T
313d0 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65  he names returne
313e0 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e  d are the origin
313f0 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61  al un-aliased na
31400 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61  mes of the.** da
31410 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
31420 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
31430 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
31440 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e  ment to these in
31450 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70  terfaces is a [p
31460 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31470 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  t]..** ^These fu
31480 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69  nctions return i
31490 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
314a0 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
314b0 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
314c0 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  by.** the statem
314d0 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
314e0 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
314f0 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
31500 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20   ^The left-most 
31510 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e  column is column
31520 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75   0 for these rou
31530 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tines..**.** ^If
31540 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
31550 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
31560 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
31570 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a  expression or.**
31580 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
31590 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
315a0 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
315b0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
315c0 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e   return.** NULL.
315d0 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
315e0 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
315f0 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
31600 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
31610 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20  rror.** occurs. 
31620 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65   ^Otherwise, the
31630 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  y return the nam
31640 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65  e of the attache
31650 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  d database, tabl
31660 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20  e,.** or column 
31670 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c  that query resul
31680 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74  t column was ext
31690 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a  racted from..**.
316a0 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20  ** ^As with all 
316b0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49  other SQLite API
316c0 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e  s, those whose n
316d0 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31  ames end with "1
316e0 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46  6" return.** UTF
316f0 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69  -16 encoded stri
31700 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65  ngs and the othe
31710 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  r functions retu
31720 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  rn UTF-8..**.** 
31730 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20  ^These APIs are 
31740 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
31750 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
31760 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
31770 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
31780 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
31790 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
317a0 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a  essor symbol..**
317b0 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
317c0 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
317d0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
317e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67  hese routines ag
317f0 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a  ainst the same.*
31800 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
31810 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  ment and column 
31820 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
31830 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
31840 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e  s are.** undefin
31850 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ed..**.** If two
31860 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
31870 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
31880 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
31890 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
318a0 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61  me | column meta
318b0 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
318c0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
318d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
318e0 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74  ment] and result
318f0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68   column.** at th
31900 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
31910 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
31920 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63   undefined..*/.c
31930 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
31940 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
31950 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  se_name(sqlite3_
31960 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
31970 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
31980 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
31990 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
319a0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
319b0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
319c0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
319d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
319e0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
319f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
31a00 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c  table_name16(sql
31a10 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
31a20 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
31a30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
31a40 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  in_name(sqlite3_
31a50 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
31a60 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
31a70 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
31a80 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
31a90 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
31aa0 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
31ab0 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41  ed Datatype Of A
31ac0 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
31ad0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
31ae0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  _stmt.**.** ^(Th
31af0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
31b00 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
31b10 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
31b20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
31b30 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
31b40 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
31b50 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
31b60 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
31b70 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
31b80 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
31b90 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
31ba0 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
31bb0 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
31bc0 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
31bd0 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
31be0 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
31bf0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e  s returned.)^  ^
31c00 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
31c10 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
31c20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
31c30 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
31c40 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
31c50 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
31c60 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  rned..** ^The re
31c70 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
31c80 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
31c90 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  coded..**.** ^(F
31ca0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
31cb0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
31cc0 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
31cd0 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
31ce0 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
31cf0 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
31d00 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
31d10 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
31d20 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
31d30 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
31d40 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
31d50 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
31d60 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
31d70 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
31d80 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
31d90 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
31da0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
31db0 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
31dc0 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
31dd0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
31de0 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
31df0 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
31e00 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65  ^So just because
31e10 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
31e20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
31e30 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
31e40 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
31e50 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
31e60 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
31e70 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
31e80 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
31e90 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
31ea0 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
31eb0 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
31ec0 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
31ed0 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a  static.  ^Type.*
31ee0 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
31ef0 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
31f00 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
31f10 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
31f20 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
31f30 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f  those values..*/
31f40 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
31f50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
31f60 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
31f70 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
31f80 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
31f90 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
31fa0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
31fb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31fc0 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20  EF: Evaluate An 
31fd0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
31fe0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
31ff0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65  _stmt.**.** Afte
32000 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
32010 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65  atement] has bee
32020 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  n prepared using
32030 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69   any of.** [sqli
32040 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
32050 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ], [sqlite3_prep
32060 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69  are_v3()], [sqli
32070 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
32080 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
32090 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
320a0 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
320b0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
320c0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
320d0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
320e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
320f0 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
32100 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
32110 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
32120 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
32130 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
32140 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
32150 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
32160 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
32170 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
32180 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
32190 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
321a0 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
321b0 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
321c0 77 65 72 20 22 76 58 22 20 69 6e 74 65 72 66 61  wer "vX" interfa
321d0 63 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ces.** [sqlite3_
321e0 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b  prepare_v3()], [
321f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
32200 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
32210 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2c  prepare16_v3()],
32220 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
32230 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
32240 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79  the older legacy
32250 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
32260 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
32270 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
32280 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
32290 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
322a0 20 6e 65 77 20 22 76 58 22 20 69 6e 74 65 72 66   new "vX" interf
322b0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
322c0 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
322d0 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
322e0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
322f0 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
32300 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
32310 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
32320 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
32330 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
32340 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
32350 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
32360 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
32370 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
32380 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
32390 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
323a0 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
323b0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
323c0 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
323d0 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
323e0 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
323f0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
32400 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
32410 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
32420 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
32430 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
32440 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
32450 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
32460 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
32470 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
32480 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
32490 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
324a0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
324b0 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
324c0 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
324d0 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
324e0 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
324f0 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
32500 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
32510 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
32520 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
32530 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
32540 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20   an.** explicit 
32550 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
32560 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
32570 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
32580 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
32590 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
325a0 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
325b0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
325c0 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
325d0 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
325e0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
325f0 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
32600 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
32610 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
32620 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
32630 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
32640 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
32650 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
32660 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
32670 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
32680 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
32690 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
326a0 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
326b0 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
326c0 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
326d0 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
326e0 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
326f0 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
32700 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
32710 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
32720 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
32730 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
32740 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
32750 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
32760 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
32770 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
32780 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
32790 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
327a0 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
327b0 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
327c0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
327d0 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
327e0 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
327f0 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
32800 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
32810 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
32820 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
32830 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
32840 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
32850 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
32860 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
32870 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
32880 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
32890 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
328a0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
328b0 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
328c0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
328d0 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
328e0 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
328f0 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
32900 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
32910 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
32920 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
32930 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
32940 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
32950 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
32960 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
32970 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
32980 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
32990 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
329a0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
329b0 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
329c0 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
329d0 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
329e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
329f0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
32a00 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
32a10 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
32a20 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
32a30 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
32a40 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
32a50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
32a60 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
32a70 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
32a80 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
32a90 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
32aa0 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
32ab0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
32ac0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
32ad0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
32ae0 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
32af0 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
32b00 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
32b10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
32b20 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
32b30 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
32b40 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
32b50 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
32b60 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
32b70 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
32b80 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
32b90 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
32ba0 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
32bb0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
32bc0 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
32bd0 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
32be0 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
32bf0 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
32c00 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
32c10 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
32c20 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
32c30 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
32c40 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
32c50 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
32c60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
32c70 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
32c80 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
32c90 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
32ca0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
32cb0 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
32cc0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
32cd0 75 74 20 61 66 74 65 72 20 5b 76 65 72 73 69 6f  ut after [versio
32ce0 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b 64 61  n 3.6.23.1] ([da
32cf0 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a  teof:3.6.23.1],.
32d00 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
32d10 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69  ) began.** calli
32d20 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
32d30 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c  t()] automatical
32d40 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75  ly in this circu
32d50 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a  mstance rather.*
32d60 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67  * than returning
32d70 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
32d80 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63  .  This is not c
32d90 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70  onsidered a comp
32da0 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65  atibility.** bre
32db0 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61  ak because any a
32dc0 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20  pplication that 
32dd0 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e  ever receives an
32de0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65   SQLITE_MISUSE e
32df0 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65  rror.** is broke
32e00 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e  n by definition.
32e10 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d    The [SQLITE_OM
32e20 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f  IT_AUTORESET] co
32e30 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
32e40 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  n.** can be used
32e50 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20   to restore the 
32e60 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e  legacy behavior.
32e70 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
32e80 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
32e90 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61  </b> In the lega
32ea0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
32eb0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
32ec0 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72  .** API always r
32ed0 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
32ee0 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51   error code, [SQ
32ef0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
32f00 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72  lowing any.** er
32f10 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
32f20 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
32f30 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
32f40 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
32f50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
32f60 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
32f70 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
32f80 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
32f90 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65  ne of the.** spe
32fa0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
32fb0 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
32fc0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
32fd0 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
32fe0 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
32ff0 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
33000 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
33010 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
33020 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
33030 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
33040 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
33050 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
33060 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
33070 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
33080 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
33090 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72  pare_v2()].** or
330a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
330b0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  e16_v2()] or [sq
330c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
330d0 76 33 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a  v3()] instead.**
330e0 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b   of the legacy [
330f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
33100 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
33110 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74  prepare16()] int
33120 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e  erfaces,.** then
33130 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
33140 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
33150 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69   are returned di
33160 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c  rectly.** by sql
33170 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68  ite3_step().  Th
33180 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 58  e use of the "vX
33190 22 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  " interfaces is 
331a0 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
331b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
331c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
331d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
331e0 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
331f0 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
33200 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  set.** METHOD: s
33210 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
33220 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
33230 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74  ata_count(P) int
33240 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
33250 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
33260 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63  umns in the.** c
33270 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
33280 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
33290 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
332a0 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70  ent] P..** ^If p
332b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
332c0 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  t P does not hav
332d0 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20  e results ready 
332e0 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69  to return.** (vi
332f0 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b  a calls to the [
33300 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
33310 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt | sqlite3_col
33320 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69  umn_*()] of.** i
33330 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20  nterfaces) then 
33340 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
33350 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e  nt(P) returns 0.
33360 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33370 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
33380 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75  outine also retu
33390 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20  rns 0 if P is a 
333a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
333b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
333c0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
333d0 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
333e0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
333f0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
33400 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
33410 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ned [SQLITE_DONE
33420 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
33430 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a  _data_count(P).*
33440 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f  * will return no
33450 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f  n-zero if previo
33460 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  us call to [sqli
33470 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
33480 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  urned.** [SQLITE
33490 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e  _ROW], except in
334a0 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65   the case of the
334b0 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65   [PRAGMA increme
334c0 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20  ntal_vacuum].** 
334d0 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20  where it always 
334e0 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e  returns zero sin
334f0 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20  ce each step of 
33500 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a  that multi-step.
33510 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e  ** pragma return
33520 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64  s 0 columns of d
33530 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ata..**.** See a
33540 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  lso: [sqlite3_co
33550 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  lumn_count()].*/
33560 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74  .int sqlite3_dat
33570 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
33580 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
33590 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
335a0 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
335b0 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
335c0 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a  : SQLITE_TEXT.**
335d0 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75  .** ^(Every valu
335e0 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
335f0 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
33600 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
33610 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
33620 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
33630 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
33640 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
33650 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
33660 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
33670 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
33680 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
33690 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
336a0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
336b0 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
336c0 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
336d0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
336e0 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
336f0 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
33700 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
33710 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
33720 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
33730 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
33740 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
33750 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
33760 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
33770 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
33780 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
33790 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
337a0 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
337b0 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
337c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
337d0 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
337e0 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
337f0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
33800 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
33810 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
33820 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
33830 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
33840 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
33850 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
33860 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
33870 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
33880 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
33890 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
338a0 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
338b0 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a   From A Query.**
338c0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
338d0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
338e0 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ons}.** METHOD: 
338f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
33900 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72 79 3a 3c 2f  ** <b>Summary:</
33910 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  b>.** <blockquot
33920 65 3e 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  e><table border=
33930 30 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 30 20  0 cellpadding=0 
33940 63 65 6c 6c 73 70 61 63 69 6e 67 3d 30 3e 0a 2a  cellspacing=0>.*
33950 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
33960 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
33970 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
33980 64 3e 42 4c 4f 42 20 72 65 73 75 6c 74 0a 2a 2a  d>BLOB result.**
33990 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
339a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
339b0 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  e</b><td>&rarr;<
339c0 74 64 3e 52 45 41 4c 20 72 65 73 75 6c 74 0a 2a  td>REAL result.*
339d0 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
339e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 3c  ite3_column_int<
339f0 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
33a00 3e 33 32 2d 62 69 74 20 49 4e 54 45 47 45 52 20  >32-bit INTEGER 
33a10 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74  result.** <tr><t
33a20 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
33a30 75 6d 6e 5f 69 6e 74 36 34 3c 2f 62 3e 3c 74 64  umn_int64</b><td
33a40 3e 26 72 61 72 72 3b 3c 74 64 3e 36 34 2d 62 69  >&rarr;<td>64-bi
33a50 74 20 49 4e 54 45 47 45 52 20 72 65 73 75 6c 74  t INTEGER result
33a60 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
33a70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
33a80 78 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  xt</b><td>&rarr;
33a90 3c 74 64 3e 55 54 46 2d 38 20 54 45 58 54 20 72  <td>UTF-8 TEXT r
33aa0 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  esult.** <tr><td
33ab0 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ><b>sqlite3_colu
33ac0 6d 6e 5f 74 65 78 74 31 36 3c 2f 62 3e 3c 74 64  mn_text16</b><td
33ad0 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d 31  >&rarr;<td>UTF-1
33ae0 36 20 54 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a  6 TEXT result.**
33af0 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
33b00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
33b10 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
33b20 64 3e 54 68 65 20 72 65 73 75 6c 74 20 61 73 20  d>The result as 
33b30 61 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  an .** [sqlite3_
33b40 76 61 6c 75 65 7c 75 6e 70 72 6f 74 65 63 74 65  value|unprotecte
33b50 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
33b60 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 3c 74 72 3e   object..** <tr>
33b70 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e  <td>&nbsp;<td>&n
33b80 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 0a 2a  bsp;<td>&nbsp;.*
33b90 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
33ba0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
33bb0 73 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  s</b><td>&rarr;<
33bc0 74 64 3e 53 69 7a 65 20 6f 66 20 61 20 42 4c 4f  td>Size of a BLO
33bd0 42 0a 2a 2a 20 6f 72 20 61 20 55 54 46 2d 38 20  B.** or a UTF-8 
33be0 54 45 58 54 20 72 65 73 75 6c 74 20 69 6e 20 62  TEXT result in b
33bf0 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ytes.** <tr><td>
33c00 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
33c10 6e 5f 62 79 74 65 73 31 36 26 6e 62 73 70 3b 26  n_bytes16&nbsp;&
33c20 6e 62 73 70 3b 3c 2f 62 3e 0a 2a 2a 20 3c 74 64  nbsp;</b>.** <td
33c30 3e 26 72 61 72 72 3b 26 6e 62 73 70 3b 26 6e 62  >&rarr;&nbsp;&nb
33c40 73 70 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 55  sp;<td>Size of U
33c50 54 46 2d 31 36 0a 2a 2a 20 54 45 58 54 20 69 6e  TF-16.** TEXT in
33c60 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74   bytes.** <tr><t
33c70 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
33c80 75 6d 6e 5f 74 79 70 65 3c 2f 62 3e 3c 74 64 3e  umn_type</b><td>
33c90 26 72 61 72 72 3b 3c 74 64 3e 44 65 66 61 75 6c  &rarr;<td>Defaul
33ca0 74 0a 2a 2a 20 64 61 74 61 74 79 70 65 20 6f 66  t.** datatype of
33cb0 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 3c   the result.** <
33cc0 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f 63 6b 71 75  /table></blockqu
33cd0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 44 65  ote>.**.** <b>De
33ce0 74 61 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a 0a 2a 2a  tails:</b>.**.**
33cf0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
33d00 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
33d10 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67  ion about a sing
33d20 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
33d30 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75   current.** resu
33d40 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
33d50 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61  y.  ^In every ca
33d60 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
33d70 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
33d80 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
33d90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33da0 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
33db0 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
33dc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
33dd0 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
33de0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
33df0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
33e00 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
33e10 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
33e20 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
33e30 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
33e40 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
33e50 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
33e60 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
33e70 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20   returned. ^The 
33e80 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
33e90 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
33ea0 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
33eb0 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65  0..** ^The numbe
33ec0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
33ed0 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62  the result can b
33ee0 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
33ef0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
33f00 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a  olumn_count()]..
33f10 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
33f20 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
33f30 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f  not currently po
33f40 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72  int to a valid r
33f50 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  ow, or if the.**
33f60 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
33f70 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
33f80 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
33f90 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65  efined..** These
33fa0 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e   routines may on
33fb0 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
33fc0 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
33fd0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
33fe0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
33ff0 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  s returned [SQLI
34000 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74  TE_ROW] and neit
34010 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
34020 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71  reset()] nor [sq
34030 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
34040 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  ] have been call
34050 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ed subsequently.
34060 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
34070 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
34080 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
34090 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
340a0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
340b0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
340c0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
340d0 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
340e0 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
340f0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
34100 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
34110 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
34120 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
34130 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
34140 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
34150 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
34160 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
34170 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
34180 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
34190 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
341a0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
341b0 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
341c0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
341d0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
341e0 68 65 20 66 69 72 73 74 20 73 69 78 20 69 6e 74  he first six int
341f0 65 72 66 61 63 65 73 20 28 5f 62 6c 6f 62 2c 20  erfaces (_blob, 
34200 5f 64 6f 75 62 6c 65 2c 20 5f 69 6e 74 2c 20 5f  _double, _int, _
34210 69 6e 74 36 34 2c 20 5f 74 65 78 74 2c 20 61 6e  int64, _text, an
34220 64 20 5f 74 65 78 74 31 36 29 0a 2a 2a 20 65 61  d _text16).** ea
34230 63 68 20 72 65 74 75 72 6e 20 74 68 65 20 76 61  ch return the va
34240 6c 75 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  lue of a result 
34250 63 6f 6c 75 6d 6e 20 69 6e 20 61 20 73 70 65 63  column in a spec
34260 69 66 69 63 20 64 61 74 61 20 66 6f 72 6d 61 74  ific data format
34270 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 72 65 73  .  If.** the res
34280 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 6f  ult column is no
34290 74 20 69 6e 69 74 69 61 6c 6c 79 20 69 6e 20 74  t initially in t
342a0 68 65 20 72 65 71 75 65 73 74 65 64 20 66 6f 72  he requested for
342b0 6d 61 74 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  mat (for example
342c0 2c 0a 2a 2a 20 69 66 20 74 68 65 20 71 75 65 72  ,.** if the quer
342d0 79 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  y returns an int
342e0 65 67 65 72 20 62 75 74 20 74 68 65 20 73 71 6c  eger but the sql
342f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
34300 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
34310 69 73 20 75 73 65 64 20 74 6f 20 65 78 74 72 61  is used to extra
34320 63 74 20 74 68 65 20 76 61 6c 75 65 29 20 74 68  ct the value) th
34330 65 6e 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20  en an automatic 
34340 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
34350 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a  is performed..**
34360 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34370 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
34380 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
34390 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
343a0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
343b0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
343c0 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
343d0 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
343e0 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20  t column.  ^The 
343f0 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
34400 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
34410 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
34420 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
34430 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
34440 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
34450 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 0a 2a 2a  SQLITE_NULL]..**
34460 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
34470 65 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  e of sqlite3_col
34480 75 6d 6e 5f 74 79 70 65 28 29 20 63 61 6e 20 62  umn_type() can b
34490 65 20 75 73 65 64 20 74 6f 20 64 65 63 69 64 65  e used to decide
344a0 20 77 68 69 63 68 0a 2a 2a 20 6f 66 20 74 68 65   which.** of the
344b0 20 66 69 72 73 74 20 73 69 78 20 69 6e 74 65 72   first six inter
344c0 66 61 63 65 20 73 68 6f 75 6c 64 20 62 65 20 75  face should be u
344d0 73 65 64 20 74 6f 20 65 78 74 72 61 63 74 20 74  sed to extract t
344e0 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e  he column value.
344f0 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65  .** The value re
34500 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
34510 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
34520 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66  is only meaningf
34530 75 6c 20 69 66 20 6e 6f 0a 2a 2a 20 61 75 74 6f  ul if no.** auto
34540 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e 76 65  matic type conve
34550 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
34560 72 72 65 64 20 66 6f 72 20 74 68 65 20 76 61 6c  rred for the val
34570 75 65 20 69 6e 20 71 75 65 73 74 69 6f 6e 2e 20  ue in question. 
34580 20 0a 2a 2a 20 41 66 74 65 72 20 61 20 74 79 70   .** After a typ
34590 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 20 74 68  e conversion, th
345a0 65 20 72 65 73 75 6c 74 20 6f 66 20 63 61 6c 6c  e result of call
345b0 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ing sqlite3_colu
345c0 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 69 73 20  mn_type().** is 
345d0 75 6e 64 65 66 69 6e 65 64 2c 20 74 68 6f 75 67  undefined, thoug
345e0 68 20 68 61 72 6d 6c 65 73 73 2e 20 20 46 75 74  h harmless.  Fut
345f0 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
34600 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68  of SQLite may ch
34610 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f  ange the behavio
34620 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r of sqlite3_col
34630 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f  umn_type().** fo
34640 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63  llowing a type c
34650 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
34660 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   If the result i
34670 73 20 61 20 42 4c 4f 42 20 6f 72 20 61 20 54 45  s a BLOB or a TE
34680 58 54 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  XT string, then 
34690 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
346a0 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 6f 72  mn_bytes().** or
346b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
346c0 62 79 74 65 73 31 36 28 29 20 69 6e 74 65 72 66  bytes16() interf
346d0 61 63 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  aces can be used
346e0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
346f0 65 20 73 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 61  e size.** of tha
34700 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
34710 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
34720 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
34730 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
34740 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
34750 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
34760 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
34770 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
34780 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
34790 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
347a0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
347b0 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
347c0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
347d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
347e0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
347f0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
34800 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
34810 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
34820 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
34830 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
34840 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
34850 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
34860 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
34870 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
34880 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
34890 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
348a0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
348b0 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
348c0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
348d0 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
348e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
348f0 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
34900 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34910 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20  bytes() returns 
34920 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  zero..**.** ^If 
34930 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
34940 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73  BLOB or UTF-16 s
34950 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
34960 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
34970 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  tes16().** routi
34980 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
34990 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
349a0 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
349b0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
349c0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
349d0 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  F-8 string, then
349e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
349f0 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72  bytes16() conver
34a00 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
34a10 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74   to UTF-16 and t
34a20 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
34a30 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
34a40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
34a50 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
34a60 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
34a70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
34a80 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  6() uses.** [sql
34a90 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
34aa0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
34ab0 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
34ac0 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  16 string and re
34ad0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
34ae0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
34af0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
34b00 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
34b10 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
34b20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
34b30 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65  s16() returns ze
34b40 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76  ro..**.** ^The v
34b50 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
34b60 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
34b70 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a  n_bytes()] and .
34b80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
34b90 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f  mn_bytes16()] do
34ba0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
34bb0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
34bc0 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20  s at the end.** 
34bd0 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20  of the string.  
34be0 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68  ^For clarity: th
34bf0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
34c00 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
34c10 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
34c20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
34c30 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
34c40 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  are the number o
34c50 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
34c60 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
34c70 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
34c80 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53  acters..**.** ^S
34c90 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
34ca0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
34cb0 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c  n_text() and sql
34cc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
34cd0 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d  16(),.** even em
34ce0 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65  pty strings, are
34cf0 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
34d00 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72  minated.  ^The r
34d10 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66  eturn.** value f
34d20 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  rom sqlite3_colu
34d30 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20  mn_blob() for a 
34d40 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
34d50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
34d60 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72  er..**.** <b>War
34d70 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f  ning:</b> ^The o
34d80 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
34d90 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
34da0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e  n_value()] is an
34db0 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
34dc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
34dd0 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75  object.  In a mu
34de0 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e 76 69  ltithreaded envi
34df0 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75  ronment,.** an u
34e00 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
34e10 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
34e20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
34e30 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20   safely with.** 
34e40 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
34e50 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
34e60 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
34e70 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
34e80 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
34e90 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
34ea0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
34eb0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
34ec0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
34ed0 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
34ee0 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
34ef0 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
34f00 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
34f10 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
34f20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
34f30 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
34f40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
34f50 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69  s()], the behavi
34f60 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  or is not thread
34f70 73 61 66 65 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20  safe..** Hence, 
34f80 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
34f90 6d 6e 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  mn_value() inter
34fa0 66 61 63 65 0a 2a 2a 20 69 73 20 6e 6f 72 6d 61  face.** is norma
34fb0 6c 6c 79 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20  lly only useful 
34fc0 77 69 74 68 69 6e 20 74 68 65 20 69 6d 70 6c 65  within the imple
34fd0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 0a 2a 2a  mentation of .**
34fe0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
34ff0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
35000 6f 6e 73 5d 20 6f 72 20 5b 76 69 72 74 75 61 6c  ons] or [virtual
35010 20 74 61 62 6c 65 73 5d 2c 20 6e 6f 74 20 77 69   tables], not wi
35020 74 68 69 6e 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  thin.** top-leve
35030 6c 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  l application co
35040 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  de..**.** The th
35050 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
35060 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
35070 65 72 74 20 74 68 65 20 64 61 74 61 74 79 70 65  ert the datatype
35080 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 0a   of the result..
35090 2a 2a 20 5e 46 6f 72 20 65 78 61 6d 70 6c 65 2c  ** ^For example,
350a0 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
350b0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
350c0 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
350d0 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
350e0 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
350f0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
35100 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
35110 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
35120 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
35130 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
35140 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
35150 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
35160 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
35170 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
35180 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
35190 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
351a0 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
351b0 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
351c0 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
351d0 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
351e0 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
351f0 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
35200 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
35210 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
35220 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
35230 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
35240 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
35250 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
35260 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
35270 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
35280 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
35290 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
352a0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
352b0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
352c0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
352d0 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
352e0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
352f0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
35300 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
35310 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
35320 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
35330 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
35340 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
35350 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
35360 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
35370 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
35380 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
35390 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
353a0 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
353b0 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
353c0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
353d0 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
353e0 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
353f0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
35400 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
35410 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
35420 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
35430 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
35440 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
35450 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41  BLOB    <td> [CA
35460 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c  ST] to BLOB.** <
35470 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
35480 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
35490 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
354a0 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
354b0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
354c0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
354d0 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
354e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
354f0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
35500 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
35510 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
35520 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
35530 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
35540 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
35550 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
35560 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
35570 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
35580 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
35590 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
355a0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64   TEXT    <td> Ad
355b0 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  d a zero termina
355c0 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a  tor if needed.**
355d0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
355e0 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
355f0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
35600 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
35610 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
35620 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
35630 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
35640 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35650 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
35660 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
35670 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
35680 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
35690 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
356a0 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
356b0 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
356c0 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
356d0 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
356e0 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
356f0 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
35700 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
35710 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
35720 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
35730 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
35740 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
35750 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
35760 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
35770 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
35780 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
35790 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
357a0 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
357b0 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
357c0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
357d0 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
357e0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
357f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
35800 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
35810 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
35820 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
35830 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
35840 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
35850 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
35860 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
35870 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
35880 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
35890 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
358a0 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
358b0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
358c0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
358d0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
358e0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
358f0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
35900 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
35910 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  </ul>.**.** ^Con
35920 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
35930 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
35940 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
35950 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
35960 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
35970 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
35980 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
35990 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
359a0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
359b0 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
359c0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72   prior pointer r
359d0 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68  eferences will h
359e0 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
359f0 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
35a00 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
35a10 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
35a20 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
35a30 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
35a40 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
35a50 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
35a60 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
35a70 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
35a80 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
35a90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65  ..**.** The safe
35aa0 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20  st policy is to 
35ab0 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75  invoke these rou
35ac0 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20  tines.** in one 
35ad0 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
35ae0 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c   ways:.**.** <ul
35af0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
35b00 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
35b10 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
35b20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
35b30 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
35b40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
35b50 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  lob() followed b
35b60 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
35b70 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
35b80 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
35b90 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f  lumn_text16() fo
35ba0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
35bb0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
35bc0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  ()</li>.** </ul>
35bd0 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  .**.** In other 
35be0 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c  words, you shoul
35bf0 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63  d call sqlite3_c
35c00 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a  olumn_text(),.**
35c10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35c20 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74  blob(), or sqlit
35c30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
35c40 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63  () first to forc
35c50 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20  e the result.** 
35c60 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64  into the desired
35c70 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e   format, then in
35c80 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  voke sqlite3_col
35c90 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
35ca0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
35cb0 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69  _bytes16() to fi
35cc0 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  nd the size of t
35cd0 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e  he result.  Do n
35ce0 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20  ot mix calls.** 
35cf0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
35d00 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  n_text() or sqli
35d10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
35d20 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a  ) with calls to.
35d30 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
35d40 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64  n_bytes16(), and
35d50 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   do not mix call
35d60 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
35d70 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  umn_text16().** 
35d80 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71  with calls to sq
35d90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
35da0 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  es()..**.** ^The
35db0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
35dc0 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74  ed are valid unt
35dd0 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  il a type conver
35de0 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a  sion occurs as.*
35df0 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76  * described abov
35e00 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c  e, or until [sql
35e10 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
35e20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
35e30 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
35e40 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
35e50 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65  called.  ^The me
35e60 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20  mory space used 
35e70 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a  to hold strings.
35e80 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20  ** and BLOBs is 
35e90 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
35ea0 6c 6c 79 2e 20 20 44 6f 20 6e 6f 74 20 70 61 73  lly.  Do not pas
35eb0 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
35ec0 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
35ed0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
35ee0 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
35ef0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
35f00 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b  , etc. into.** [
35f10 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
35f20 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65  .**.** ^(If a me
35f30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
35f40 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
35f50 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
35f60 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
35f70 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
35f80 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
35f90 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
35fa0 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
35fb0 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
35fc0 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
35fd0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
35fe0 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
35ff0 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
36000 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
36010 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
36020 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
36030 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
36040 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f  _NOMEM].)^.*/.co
36050 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
36060 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
36070 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
36080 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73   iCol);.double s
36090 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
360a0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
360b0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
360c0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
360d0 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
360e0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
360f0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
36100 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
36110 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
36120 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
36130 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
36140 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
36150 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
36160 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
36170 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
36180 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
36190 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
361a0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
361b0 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74  te3_value *sqlit
361c0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
361d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
361e0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
361f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
36200 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  es(sqlite3_stmt*
36210 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
36220 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36230 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
36240 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
36250 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
36260 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65  lumn_type(sqlite
36270 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
36280 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
36290 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
362a0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
362b0 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54  t Object.** DEST
362c0 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f  RUCTOR: sqlite3_
362d0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
362e0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
362f0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
36300 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
36310 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
36320 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74  ement]..** ^If t
36330 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
36340 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65  valuation of the
36350 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75   statement encou
36360 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73  ntered no errors
36370 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74  .** or if the st
36380 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72  atement is never
36390 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c   been evaluated,
363a0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69   then sqlite3_fi
363b0 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73  nalize() returns
363c0 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20  .** SQLITE_OK.  
363d0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
363e0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
363f0 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61  f statement S fa
36400 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  iled, then.** sq
36410 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
36420 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70  ) returns the ap
36430 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
36440 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
36450 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
36460 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  e]..**.** ^The s
36470 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
36480 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  S) routine can b
36490 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
364a0 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20  point during.** 
364b0 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f  the life cycle o
364c0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
364d0 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66  ement] S:.** bef
364e0 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20  ore statement S 
364f0 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65  is ever evaluate
36500 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20  d, after.** one 
36510 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f  or more calls to
36520 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
36530 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79  )], or after any
36540 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c   call.** to [sql
36550 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67  ite3_step()] reg
36560 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
36570 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74  er or not the st
36580 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63  atement has.** c
36590 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
365a0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b  on..**.** ^Invok
365b0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  ing sqlite3_fina
365c0 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c  lize() on a NULL
365d0 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61   pointer is a ha
365e0 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
365f0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
36600 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a  ion must finaliz
36610 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65  e every [prepare
36620 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
36630 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a  order to avoid.*
36640 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73  * resource leaks
36650 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76  .  It is a griev
36660 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68  ous error for th
36670 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  e application to
36680 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61   try to use.** a
36690 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
366a0 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
366b0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e   been finalized.
366c0 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70    Any use of a p
366d0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
366e0 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
366f0 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
36700 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75   can result in u
36710 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20  ndefined and.** 
36720 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
36730 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67  vior such as seg
36740 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20  faults and heap 
36750 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69  corruption..*/.i
36760 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
36770 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
36780 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
36790 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
367a0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
367b0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
367c0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
367d0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  stmt.**.** The s
367e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66  qlite3_reset() f
367f0 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
36800 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72  d to reset a [pr
36810 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
36820 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b  ].** object back
36830 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
36840 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20  state, ready to 
36850 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a  be re-executed..
36860 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74  ** ^Any SQL stat
36870 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20  ement variables 
36880 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20  that had values 
36890 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73  bound to them us
368a0 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ing.** the [sqli
368b0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
368c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
368d0 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65   API] retain the
368e0 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73  ir values..** Us
368f0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  e [sqlite3_clear
36900 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20  _bindings()] to 
36910 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e  reset the bindin
36920 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  gs..**.** ^The [
36930 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
36940 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
36950 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  ts the [prepared
36960 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
36970 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67   back to the beg
36980 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72  inning of its pr
36990 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ogram..**.** ^If
369a0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
369b0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
369c0 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
369d0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
369e0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74  statement] S ret
369f0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
36a00 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  W] or [SQLITE_DO
36a10 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73  NE],.** or if [s
36a20 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
36a30 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65  has never before
36a40 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20   been called on 
36a50 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69  S,.** then [sqli
36a60 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
36a70 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
36a80 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
36a90 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
36aa0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
36ab0 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
36ac0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
36ad0 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74  ement] S indicat
36ae0 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65  ed an error, the
36af0 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  n.** [sqlite3_re
36b00 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
36b10 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
36b20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
36b30 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
36b40 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
36b50 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68  face does not ch
36b60 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a  ange the values.
36b70 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74  ** of any [sqlit
36b80 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e  e3_bind_blob|bin
36b90 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70  dings] on the [p
36ba0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36bb0 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  t] S..*/.int sql
36bc0 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74  ite3_reset(sqlit
36bd0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
36be0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36bf0 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65  : Create Or Rede
36c00 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f  fine SQL Functio
36c10 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
36c20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  {function creati
36c30 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20  on routines}.** 
36c40 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
36c50 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
36c60 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20  QL function}.** 
36c70 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
36c80 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
36c90 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  QL functions}.**
36ca0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
36cb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
36cc0 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74  nctions (collect
36cd0 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22  ively known as "
36ce0 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
36cf0 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20  n routines").** 
36d00 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
36d10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
36d20 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74   aggregates or t
36d30 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62  o redefine the b
36d40 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78  ehavior.** of ex
36d50 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74  isting SQL funct
36d60 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
36d70 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69  es.  The only di
36d80 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65  fferences betwee
36d90 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69  n.** these routi
36da0 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74  nes are the text
36db0 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74   encoding expect
36dc0 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65  ed for.** the se
36dd0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28  cond parameter (
36de0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
36df0 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63  function being c
36e00 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74  reated).** and t
36e10 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61  he presence or a
36e20 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74  bsence of a dest
36e30 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
36e40 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  for.** the appli
36e50 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
36e60 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
36e70 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
36e80 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
36e90 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
36ea0 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
36eb0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
36ec0 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61  be added.  ^If a
36ed0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
36ee0 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
36ef0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
36f00 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70  nection then app
36f10 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36f20 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d   SQL functions m
36f30 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20  ust be added.** 
36f40 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
36f50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61   connection sepa
36f60 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  rately..**.** ^T
36f70 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
36f80 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
36f90 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
36fa0 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
36fb0 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
36fc0 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20  d.  ^The length 
36fd0 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
36fe0 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
36ff0 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a  tes in a UTF-8.*
37000 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  * representation
37010 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  , exclusive of t
37020 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
37030 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  or.  ^Note that 
37040 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67  the name.** leng
37050 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55  th limit is in U
37060 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20  TF-8 bytes, not 
37070 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55  characters nor U
37080 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a  TF-16 bytes.  .*
37090 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74  * ^Any attempt t
370a0 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74  o create a funct
370b0 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65  ion with a longe
370c0 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72  r name.** will r
370d0 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45  esult in [SQLITE
370e0 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72  _MISUSE] being r
370f0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
37100 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
37110 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
37120 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
37130 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
37140 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
37150 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
37160 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70  akes. ^If this p
37170 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20  arameter is -1, 
37180 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
37190 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
371a0 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
371b0 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
371c0 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30  uments between 0
371d0 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a   and the limit.*
371e0 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65  * set by [sqlite
371f0 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
37200 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
37210 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74  ARG]).  If the t
37220 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
37230 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d  r is less than -
37240 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
37250 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62  n 127 then the b
37260 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
37270 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
37280 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
37290 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20  eter, eTextRep, 
372a0 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a  specifies what.*
372b0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
372c0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
372d0 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f  this SQL functio
372e0 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a  n prefers for.**
372f0 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e   its parameters.
37300 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
37310 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69  n should set thi
37320 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
37330 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  * [SQLITE_UTF16L
37340 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74 69  E] if the functi
37350 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
37360 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73  n invokes .** [s
37370 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
37380 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69  t16le()] on an i
37390 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45  nput, or [SQLITE
373a0 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74 68 65  _UTF16BE] if the
373b0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
373c0 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69  on invokes [sqli
373d0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
373e0 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75  be()] on an inpu
373f0 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  t, or.** [SQLITE
37400 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69  _UTF16] if [sqli
37410 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
37420 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20  ()] is used, or 
37430 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a  [SQLITE_UTF8].**
37440 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68   otherwise.  ^Th
37450 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
37460 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73  ion may be regis
37470 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74  tered multiple t
37480 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69  imes using.** di
37490 66 66 65 72 65 6e 74 20 70 72 65 66 65 72 72 65  fferent preferre
374a0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
374b0 2c 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  , with different
374c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
374d0 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63   for.** each enc
374e0 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20  oding..** ^When 
374f0 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
37500 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
37510 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72  same function ar
37520 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c  e available, SQL
37530 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b  ite.** will pick
37540 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e   the one that in
37550 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74  volves the least
37560 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
37570 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
37580 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
37590 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69  rameter may opti
375a0 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77  onally be ORed w
375b0 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45  ith [SQLITE_DETE
375c0 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f  RMINISTIC].** to
375d0 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65   signal that the
375e0 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61   function will a
375f0 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65  lways return the
37600 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76   same result giv
37610 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69  en.** the same i
37620 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61 20 73  nputs within a s
37630 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
37640 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66  ent.  Most SQL f
37650 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20  unctions are.** 
37660 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20  deterministic.  
37670 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61  The built-in [ra
37680 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63  ndom()] SQL func
37690 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70  tion is an examp
376a0 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74  le of a.** funct
376b0 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ion that is not 
376c0 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20  deterministic.  
376d0 54 68 65 20 53 51 4c 69 74 65 20 71 75 65 72 79  The SQLite query
376e0 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65   planner is able
376f0 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61   to.** perform a
37700 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69  dditional optimi
37710 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72  zations on deter
37720 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f  ministic functio
37730 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66  ns, so use.** of
37740 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54   the [SQLITE_DET
37750 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67  ERMINISTIC] flag
37760 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
37770 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a  where possible..
37780 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74  **.** ^(The fift
37790 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
377a0 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
377b0 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
377c0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  entation of the.
377d0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ** function can 
377e0 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
377f0 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
37800 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  g [sqlite3_user_
37810 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a  data()].)^.**.**
37820 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76   ^The sixth, sev
37830 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20  enth and eighth 
37840 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e  parameters, xFun
37850 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  c, xStep and xFi
37860 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e  nal, are.** poin
37870 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61  ters to C-langua
37880 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ge functions tha
37890 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
378a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
378b0 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41  ** aggregate. ^A
378c0 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
378d0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
378e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
378f0 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20  of the xFunc.** 
37900 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e  callback only; N
37910 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73  ULL pointers mus
37920 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  t be passed as t
37930 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  he xStep and xFi
37940 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  nal.** parameter
37950 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65  s. ^An aggregate
37960 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
37970 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
37980 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65  entation of xSte
37990 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20  p.** and xFinal 
379a0 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  and NULL pointer
379b0 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
379c0 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64  for xFunc. ^To d
379d0 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e  elete an existin
379e0 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  g.** SQL functio
379f0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
37a00 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  pass NULL pointe
37a10 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65  rs for all three
37a20 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c   function.** cal
37a30 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lbacks..**.** ^(
37a40 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72  If the ninth par
37a50 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
37a60 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
37a70 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55  n_v2() is not NU
37a80 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  LL,.** then it i
37a90 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  s destructor for
37aa0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
37ab0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a   data pointer. .
37ac0 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  ** The destructo
37ad0 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  r is invoked whe
37ae0 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  n the function i
37af0 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65  s deleted, eithe
37b00 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76  r by being.** ov
37b10 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e  erloaded or when
37b20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
37b30 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
37b40 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72  )^.** ^The destr
37b50 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e  uctor is also in
37b60 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c  voked if the cal
37b70 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
37b80 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
37b90 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e  v2() fails..** ^
37ba0 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63  When the destruc
37bb0 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  tor callback of 
37bc0 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65  the tenth parame
37bd0 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ter is invoked, 
37be0 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  it.** is passed 
37bf0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
37c00 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70  t which is a cop
37c10 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  y of the applica
37c20 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f  tion data .** po
37c30 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20  inter which was 
37c40 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  the fifth parame
37c50 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
37c60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
37c70 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  2()..**.** ^It i
37c80 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72  s permitted to r
37c90 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65  egister multiple
37ca0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
37cb0 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
37cc0 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74  functions with t
37cd0 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
37ce0 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66   with either dif
37cf0 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f  fering numbers o
37d00 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f  f.** arguments o
37d10 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66  r differing pref
37d20 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
37d30 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77  ings.  ^SQLite w
37d40 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69  ill use.** the i
37d50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
37d60 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  at most closely 
37d70 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
37d80 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
37d90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
37da0 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69  used.  ^A functi
37db0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
37dc0 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67  n with a non-neg
37dd0 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61  ative.** nArg pa
37de0 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74  rameter is a bet
37df0 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ter match than a
37e00 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
37e10 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a  entation with.**
37e20 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67   a negative nArg
37e30 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  .  ^A function w
37e40 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72  here the preferr
37e50 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
37e60 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20  .** matches the 
37e70 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e  database encodin
37e80 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a  g is a better.**
37e90 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
37ea0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
37eb0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
37ec0 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20  ferent.  .** ^A 
37ed0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
37ee0 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
37ef0 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65  erence is betwee
37f00 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54  n UTF16le and UT
37f10 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c  F16be.** is a cl
37f20 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  oser match than 
37f30 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
37f40 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
37f50 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62  fference is.** b
37f60 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20  etween UTF8 and 
37f70 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75  UTF16..**.** ^Bu
37f80 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73  ilt-in functions
37f90 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64   may be overload
37fa0 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63  ed by new applic
37fb0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
37fc0 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  nctions..**.** ^
37fd0 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  An application-d
37fe0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
37ff0 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
38000 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51  call other.** SQ
38010 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e  Lite interfaces.
38020 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20    However, such 
38030 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a  calls must not.*
38040 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  * close the data
38050 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
38060 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20  nor finalize or 
38070 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
38080 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
38090 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e  in which the fun
380a0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
380b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
380c0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
380d0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
380e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
380f0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
38100 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
38110 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
38120 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
38130 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
38140 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
38150 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
38160 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
38170 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
38180 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
38190 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
381a0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
381b0 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
381c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
381d0 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
381e0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
381f0 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
38200 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
38210 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
38220 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
38230 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
38240 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
38250 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
38260 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
38270 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
38280 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
38290 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
382a0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
382b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
382c0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
382d0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
382e0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
382f0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
38300 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
38310 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
38320 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
38330 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
38340 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
38350 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
38360 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
38370 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
38380 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
38390 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
383a0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
383b0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
383c0 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76  3_context*),.  v
383d0 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
383e0 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
383f0 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
38400 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54  ncodings.**.** T
38410 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
38420 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
38430 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
38440 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
38450 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
38460 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
38470 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
38480 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
38490 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20 49 4d        1    /* IM
384a0 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35 36 36  P: R-37514-35566
384b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
384c0 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
384d0 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52    2    /* IMP: R
384e0 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a  -03371-37637 */.
384f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
38500 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 20  TF16BE        3 
38510 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39     /* IMP: R-519
38520 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65 66  71-34154 */.#def
38530 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
38540 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
38550 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
38560 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
38570 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
38580 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
38590 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23   Deprecated */.#
385a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
385b0 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
385c0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
385d0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
385e0 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
385f0 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
38600 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  Flags.**.** Thes
38610 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20  e constants may 
38620 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72  be ORed together
38630 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
38640 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65  QLITE_UTF8 | pre
38650 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
38660 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75  ding] as the fou
38670 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rth argument.** 
38680 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
38690 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20  te_function()], 
386a0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
386b0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f  function16()], o
386c0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  r.** [sqlite3_cr
386d0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
386e0 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
386f0 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
38700 53 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f  STIC    0x800../
38710 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
38720 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69  eprecated Functi
38730 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45  ons.** DEPRECATE
38740 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  D.**.** These fu
38750 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70  nctions are [dep
38760 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72  recated].  In or
38770 64 65 72 20 74 6f