/ Hex Artifact Content
Login

Artifact 73a75cc53b5017525332ff3db2f74bb2607f1e8c0e8974d4afa3df3786f70aab:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c  ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a  ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66  .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53  _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f   file.  ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72  us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20  s might include 
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70  nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76  lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65  erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20  atch the macros 
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72  in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72  , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69  e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d  cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68  piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20  ing library and 
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a  header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28  <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51  ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65  ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30  ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c  BER].  ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20  rocessor macro. 
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74   Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73  e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f  ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67  py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74  amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61  he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68  racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20  e hash might be 
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b  different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1e00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1e10: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1e20: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1e30: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1e40: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1e50: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1e60: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1e70: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1e80: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1e90: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1ea0: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1eb0: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1ec0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1ed0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1ee0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1ef0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1f00: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1f10: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1f20: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1f30: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1f40: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1f50: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1f60: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1f70: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1f80: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1f90: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1fa0: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1fb0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1fc0: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1fd0: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1fe0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1ff0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
2000: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
2010: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
2020: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
2030: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
2040: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
2050: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
2060: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
2070: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
2080: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
2090: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
20a0: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
20b0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
20c0: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
20d0: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
20e0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
20f0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
2100: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
2110: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
2120: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
2130: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2140: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2150: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2160: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2170: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
2180: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
2190: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
21a0: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
21b0: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
21c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
21d0: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
21e0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
21f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2200: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
2210: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
2220: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
2230: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2240: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2250: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2260: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
2290: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
22a0: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
22b0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
22c0: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
22d0: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
22e0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
22f0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
2300: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
2310: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
2320: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
2330: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2340: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2350: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2360: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2370: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
2380: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
2390: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
23a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
23b0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
23c0: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
23d0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
23e0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
23f0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
2400: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
2410: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
2420: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2430: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2440: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2450: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2460: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2470: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2480: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2490: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
24a0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
24b0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
24c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
24d0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
24e0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
24f0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
2500: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2510: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
2520: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2530: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2540: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2550: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2560: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2570: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2580: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2590: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
25a0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
25b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
25c0: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
25d0: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
25e0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
25f0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
2600: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
2610: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
2620: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
2630: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2640: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2650: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2660: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2670: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2680: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2690: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
26a0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
26b0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
26c0: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
26d0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
26e0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
26f0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
2700: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
2710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2730: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2740: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2750: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2760: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2770: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2780: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2790: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
27a0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
27b0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
27c0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
27d0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
27e0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
27f0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
2800: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2810: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
2820: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
2830: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2840: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2850: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2860: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2870: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2880: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2890: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
28a0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
28b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
28c0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
28d0: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
28e0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
28f0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
2900: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
2910: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2920: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
2930: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2940: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2950: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2960: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2970: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2980: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2990: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
29a0: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
29b0: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
29c0: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
29d0: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
29e0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
29f0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
2a00: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2a10: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2a20: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
2a30: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2a40: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2a50: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2a60: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2a70: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2a80: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2a90: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2aa0: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45  ;.# ifdef SQLITE
2ab0: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20  _UINT64_TYPE.   
2ac0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2ad0: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  UINT64_TYPE sqli
2ae0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73  te_uint64;.# els
2af0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20  e  .    typedef 
2b00: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2b20: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69  e_uint64;.# endi
2b30: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  f.#elif defined(
2b40: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2b50: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2b60: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2b70: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2b80: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2b90: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2ba0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2bb0: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2bc0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2bd0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2be0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2bf0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2c00: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2c10: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2c30: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2c40: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2c50: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2c60: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2c70: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2c80: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2c90: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2ca0: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2cb0: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2cc0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2cd0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2ce0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2cf0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2d00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2d10: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2d20: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2d30: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2d40: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2d50: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2d60: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2d70: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2d80: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2d90: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2da0: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2db0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2dc0: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2dd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2de0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2df0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2e00: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2e10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2e20: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2e30: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2e40: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2e50: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2e60: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2e80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e90: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2ea0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2eb0: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2ec0: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ed0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2ee0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2ef0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2f00: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2f10: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2f20: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2f30: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2f40: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2f50: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2f60: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2f70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2f80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2f90: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2fa0: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2fb0: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2fc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fd0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2fe0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2ff0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
3000: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
3010: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
3020: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
3030: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
3040: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
3050: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
3060: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
3070: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
3080: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
3090: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
30a0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
30b0: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
30c0: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
30d0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
30e0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
30f0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
3100: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
3110: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
3120: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
3130: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3140: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3150: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
3160: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3170: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3180: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3190: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
31a0: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
31b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
31c0: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
31d0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
31e0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31f0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
3200: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
3210: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
3220: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
3230: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3240: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3250: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3260: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3270: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3280: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3290: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
32a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32b0: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
32c0: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
32d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
32e0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
32f0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
3300: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
3310: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3320: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3330: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3340: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3350: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3360: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3370: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3380: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3390: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
33a0: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
33b0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
33c0: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
33d0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
33e0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
33f0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3400: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3410: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3420: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3440: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3450: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3460: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3470: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3480: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3490: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
34a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
34b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
34c0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
34d0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
34e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
34f0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3500: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3510: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3520: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3530: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3540: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3550: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3560: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3570: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3580: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3590: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35a0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
35b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
35c0: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
35d0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
35e0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
35f0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
3600: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
3610: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
3620: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3630: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3640: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3650: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3660: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3670: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3680: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3690: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
36a0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
36b0: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
36c0: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
36d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
36e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
36f0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
3700: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
3710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
3720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
3730: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3740: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3750: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
3760: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
3770: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
3780: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
3790: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
37a0: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
37b0: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
37c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
37e0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
37f0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
3800: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
3810: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
3820: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
3830: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
3840: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
3850: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
3860: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3870: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
3880: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
3890: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
38a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
38b0: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
38c0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
38d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
38e0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
38f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
3900: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
3910: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
3920: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
3930: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3940: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3950: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3960: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
3970: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3980: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
3990: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
39a0: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
39b0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
39c0: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
39d0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
39e0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
39f0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
3a00: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
3a10: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
3a20: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
3a30: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3a40: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
3a50: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
3a60: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3a70: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3a80: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
3a90: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3aa0: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3ab0: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3ac0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3ad0: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
3ae0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3af0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3b00: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
3b10: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
3b20: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
3b30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3b40: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
3b50: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3b60: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
3b70: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
3b90: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3ba0: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3bb0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3bc0: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3bd0: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3be0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3bf0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3c00: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3c10: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3c20: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3c30: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3c40: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3c50: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3c60: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3c70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3c90: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3ca0: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3cb0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3cc0: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3cd0: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3ce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3cf0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3d00: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3d10: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3d20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3d30: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3d40: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3d50: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3d60: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3d70: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3d80: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3d90: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3da0: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3db0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3dc0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3dd0: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3de0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3df0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3e00: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3e10: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3e20: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3e30: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3e40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3e60: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3e70: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e80: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3e90: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3ea0: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3eb0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3ec0: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3ed0: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ee0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3ef0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3f00: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3f10: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3f20: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3f30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3f40: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3f50: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3f60: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3f70: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3f80: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3f90: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3fa0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3fb0: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3fc0: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3fd0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3fe0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3ff0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
4000: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
4010: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
4020: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
4030: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
4040: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
4050: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
4060: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
4070: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
4080: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
4090: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
40a0: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
40b0: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
40c0: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
40d0: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
40e0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
40f0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
4100: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
4110: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
4120: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
4130: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
4140: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4150: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
4160: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
4170: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
4180: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
4190: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
41a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
41b0: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
41c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
41d0: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
41e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
41f0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
4200: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
4210: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4220: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
4230: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4240: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4250: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4260: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4270: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
4280: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
4290: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
42a0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
42b0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
42c0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
42d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
42e0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
42f0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
4300: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4310: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4330: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4340: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4350: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4370: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4380: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4390: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
43a0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
43b0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
43c0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
43d0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
43e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4400: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4410: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4420: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4430: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4450: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4460: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4470: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4480: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4490: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
44a0: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
44b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
44c0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
44d0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
44e0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
44f0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
4500: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4510: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4520: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4530: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4540: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4550: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4560: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4570: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4580: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4590: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
45a0: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
45b0: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
45c0: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
45d0: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
45e0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
45f0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4610: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
4620: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72  /* Generic error
4630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4640: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4650: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4660: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4670: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4680: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4690: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
46a0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
46b0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
46c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
46d0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
46e0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
46f0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
4700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4710: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
4720: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4730: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4760: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4770: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4780: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4790: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
47a0: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
47b0: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
47c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
47d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
47e0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
47f0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
4800: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
4810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4820: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4830: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4840: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4850: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4870: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4880: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4890: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
48a0: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
48b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
48c0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
48d0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
48e0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
48f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4900: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
4910: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
4920: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4930: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4940: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4950: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4960: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4970: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4980: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4990: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
49a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
49b0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
49c0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
49d0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
49e0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
49f0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
4a00: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
4a10: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
4a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4a30: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4a40: 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20 6f  * Internal use o
4a50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
4a60: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4a70: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4a80: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4a90: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4aa0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4ab0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4ac0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
4ad0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
4ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4af0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4b00: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4b10: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4b20: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4b30: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4b40: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4b50: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4b60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b70: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4b80: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4b90: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bb0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4bc0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4bd0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4be0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4c00: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4c10: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4c20: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4c30: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4c40: 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 20      24   /* Not 
4c50: 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
4c60: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4c70: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4c80: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4c90: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4ca0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4cb0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4cc0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4cd0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
4ce0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
4cf0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
4d10: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4d20: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4d30: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4d50: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4d60: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4d70: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4d90: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4da0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4db0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4dc0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4dd0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4de0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4df0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4e00: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4e10: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4e20: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4e30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4e40: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4e50: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4e60: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4e70: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4e80: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4e90: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4ea0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4eb0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ec0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4ed0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4ee0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4ef0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4f00: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4f10: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4f20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f30: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4f40: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4f50: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4f60: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4f70: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4f80: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4f90: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4fa0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4fb0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4fc0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4fd0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4fe0: 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33  .3.8 [dateof:3.3
4ff0: 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72  .8].** and later
5000: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
5010: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
5020: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
5030: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
5040: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
5050: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
5060: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b   errors. These [
5070: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
5080: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c  codes] are enabl
5090: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
50a0: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
50b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
50c0: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
50d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
50e0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
50f0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68  ()] API.  Or, th
5100: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20  e extended code 
5110: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20  for.** the most 
5120: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e  recent error can
5130: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69   be obtained usi
5140: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
5150: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
5160: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
5170: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
5180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
5190: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
51a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
51b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
51c0: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
51d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
51e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
51f0: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
5200: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5210: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
5220: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5230: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
5240: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
5260: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5270: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
5280: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
52a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52b0: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
52c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52d0: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
52e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52f0: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
5300: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5310: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
5320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5330: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
5340: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5350: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5370: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5390: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
53a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53b0: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
53c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53d0: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
53e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53f0: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
5400: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5410: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
5420: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5430: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
5440: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5450: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
5460: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5470: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
5480: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5490: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
54a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
54b0: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
54c0: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
54d0: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
54e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
54f0: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
5500: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5510: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
5520: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5530: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
5540: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5550: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
5560: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5570: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
5580: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5590: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
55a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
55b0: 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20  RR_SHMOPEN      
55c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
55d0: 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64  RR | (18<<8)).#d
55e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
55f0: 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20  RR_SHMSIZE      
5600: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5610: 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64  RR | (19<<8)).#d
5620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5630: 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20  RR_SHMLOCK      
5640: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5650: 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64  RR | (20<<8)).#d
5660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5670: 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20  RR_SHMMAP       
5680: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5690: 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64  RR | (21<<8)).#d
56a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
56b0: 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20  RR_SEEK         
56c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
56d0: 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64  RR | (22<<8)).#d
56e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
56f0: 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20  RR_DELETE_NOENT 
5700: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5710: 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64  RR | (23<<8)).#d
5720: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5730: 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20  RR_MMAP         
5740: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5750: 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64  RR | (24<<8)).#d
5760: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5770: 52 52 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20  RR_GETTEMPPATH  
5780: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5790: 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64  RR | (25<<8)).#d
57a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
57b0: 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  RR_CONVPATH     
57c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
57d0: 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64  RR | (26<<8)).#d
57e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
57f0: 52 52 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20  RR_VNODE        
5800: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5810: 52 52 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64  RR | (27<<8)).#d
5820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5830: 52 52 5f 41 55 54 48 20 20 20 20 20 20 20 20 20  RR_AUTH         
5840: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5850: 52 52 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64  RR | (28<<8)).#d
5860: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5870: 52 52 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20  RR_BEGIN_ATOMIC 
5880: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5890: 52 52 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64  RR | (29<<8)).#d
58a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
58b0: 52 52 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43  RR_COMMIT_ATOMIC
58c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
58d0: 52 52 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64  RR | (30<<8)).#d
58e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
58f0: 52 52 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  RR_ROLLBACK_ATOM
5900: 49 43 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45  IC   (SQLITE_IOE
5910: 52 52 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64  RR | (31<<8)).#d
5920: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
5930: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
5940: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
5950: 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  KED |  (1<<8)).#
5960: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5970: 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  SY_RECOVERY     
5980: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5990: 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a  SY   |  (1<<8)).
59a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
59b0: 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20  USY_SNAPSHOT    
59c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
59d0: 55 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29  USY   |  (2<<8))
59e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59f0: 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44  CANTOPEN_NOTEMPD
5a00: 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  IR      (SQLITE_
5a10: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38  CANTOPEN | (1<<8
5a20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a30: 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52  E_CANTOPEN_ISDIR
5a40: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5a50: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c  E_CANTOPEN | (2<
5a60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a70: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c  ITE_CANTOPEN_FUL
5a80: 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  LPATH       (SQL
5a90: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5aa0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5ab0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43  QLITE_CANTOPEN_C
5ac0: 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53  ONVPATH       (S
5ad0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5ae0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5af0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5b00: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
5b10: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5b20: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5b30: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5b40: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5b50: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5b60: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<8)).#def
5b70: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5b80: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
5b90: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5ba0: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  NLY | (2<<8)).#d
5bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5bc0: 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20  DONLY_ROLLBACK  
5bd0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5be0: 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a  DONLY | (3<<8)).
5bf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5c00: 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20  EADONLY_DBMOVED 
5c10: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5c20: 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29  EADONLY | (4<<8)
5c30: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5c40: 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20  _ABORT_ROLLBACK 
5c50: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5c60: 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29  _ABORT | (2<<8))
5c70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c80: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b  CONSTRAINT_CHECK
5c90: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5ca0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c  CONSTRAINT | (1<
5cb0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5cc0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5cd0: 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c  OMMITHOOK   (SQL
5ce0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5cf0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5d00: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5d10: 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20  NT_FOREIGNKEY   
5d20: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5d30: 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  NT | (3<<8)).#de
5d40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5d50: 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20  TRAINT_FUNCTION 
5d60: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5d70: 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29  TRAINT | (4<<8))
5d80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d90: 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55  CONSTRAINT_NOTNU
5da0: 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  LL      (SQLITE_
5db0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c  CONSTRAINT | (5<
5dc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5dd0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50  ITE_CONSTRAINT_P
5de0: 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c  RIMARYKEY   (SQL
5df0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5e00: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
5e10: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5e20: 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  NT_TRIGGER      
5e30: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5e40: 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  NT | (7<<8)).#de
5e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5e60: 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20  TRAINT_UNIQUE   
5e70: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5e80: 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29  TRAINT | (8<<8))
5e90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ea0: 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20  CONSTRAINT_VTAB 
5eb0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5ec0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c  CONSTRAINT | (9<
5ed0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5ee0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52  ITE_CONSTRAINT_R
5ef0: 4f 57 49 44 20 20 20 20 20 20 20 20 28 53 51 4c  OWID        (SQL
5f00: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5f10: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
5f20: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52   SQLITE_NOTICE_R
5f30: 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20  ECOVER_WAL      
5f40: 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c  (SQLITE_NOTICE |
5f50: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5f60: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52   SQLITE_NOTICE_R
5f70: 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20  ECOVER_ROLLBACK 
5f80: 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c  (SQLITE_NOTICE |
5f90: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5fa0: 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f   SQLITE_WARNING_
5fb0: 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20  AUTOINDEX       
5fc0: 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20  (SQLITE_WARNING 
5fd0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5fe0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53  e SQLITE_AUTH_US
5ff0: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ER              
6000: 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20   (SQLITE_AUTH | 
6010: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
6020: 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50  SQLITE_OK_LOAD_P
6030: 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20 20 20 28  ERMANENTLY     (
6040: 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c  SQLITE_OK | (1<<
6050: 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  8))../*.** CAPI3
6060: 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46  REF: Flags For F
6070: 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69  ile Open Operati
6080: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
6090: 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69  bit values are i
60a0: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
60b0: 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61  in the.** 3rd pa
60c0: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
60d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
60e0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64  )] interface and
60f0: 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70  .** in the 4th p
6100: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
6110: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
6120: 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23  en] method..*/.#
6130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6140: 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  EN_READONLY     
6150: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20      0x00000001  
6160: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6170: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6180: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6190: 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20  EN_READWRITE    
61a0: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20      0x00000002  
61b0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
61c0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
61d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
61e0: 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20  EN_CREATE       
61f0: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20      0x00000004  
6200: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6210: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6220: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6230: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
6240: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20      0x00000008  
6250: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6260: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6270: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  EN_EXCLUSIVE    
6280: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20      0x00000010  
6290: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
62a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
62b0: 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20  EN_AUTOPROXY    
62c0: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20      0x00000020  
62d0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
62e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
62f0: 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20  EN_URI          
6300: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20      0x00000040  
6310: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6320: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6340: 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20  EN_MEMORY       
6350: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20      0x00000080  
6360: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6370: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6380: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6390: 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20  EN_MAIN_DB      
63a0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20      0x00000100  
63b0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
63c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
63d0: 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20  EN_TEMP_DB      
63e0: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20      0x00000200  
63f0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6400: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6410: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20  EN_TRANSIENT_DB 
6420: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20      0x00000400  
6430: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6440: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6450: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20  EN_MAIN_JOURNAL 
6460: 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20      0x00000800  
6470: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6480: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6490: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20  EN_TEMP_JOURNAL 
64a0: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20      0x00001000  
64b0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
64c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
64d0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20  EN_SUBJOURNAL   
64e0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20      0x00002000  
64f0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6500: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6510: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
6520: 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20  L   0x00004000  
6530: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6540: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6550: 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20  EN_NOMUTEX      
6560: 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20      0x00008000  
6570: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6580: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
65a0: 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20  EN_FULLMUTEX    
65b0: 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20      0x00010000  
65c0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
65d0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
65e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
65f0: 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  EN_SHAREDCACHE  
6600: 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20      0x00020000  
6610: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6620: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6630: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6640: 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
6650: 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20      0x00040000  
6660: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6670: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6680: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6690: 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  EN_WAL          
66a0: 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20      0x00080000  
66b0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a  /* VFS only */..
66c0: 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20  /* Reserved:    
66d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
66e0: 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20       0x00F00000 
66f0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
6700: 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61  EF: Device Chara
6710: 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  cteristics.**.**
6720: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
6730: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
6740: 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  od of the [sqlit
6750: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
6760: 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73  * object returns
6770: 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
6780: 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66  h is a vector of
6790: 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61   these.** bit va
67a0: 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20  lues expressing 
67b0: 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74  I/O characterist
67c0: 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20  ics of the mass 
67d0: 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63  storage.** devic
67e0: 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65  e that holds the
67f0: 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b   file that the [
6800: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6810: 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f  ds].** refers to
6820: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
6830: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
6840: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
6850: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
6860: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
6870: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
6880: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6890: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
68a0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
68b0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
68c0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
68d0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
68e0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
68f0: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
6900: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
6910: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
6920: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
6930: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
6940: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
6950: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
6960: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
6970: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
6980: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
6990: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
69a0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
69b0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
69c0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
69d0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
69e0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
69f0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
6a00: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
6a10: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
6a20: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
6a30: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
6a40: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
6a50: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20  * to xWrite().  
6a60: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6a70: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
6a80: 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65  RITE property me
6a90: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65  ans that.** afte
6aa0: 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69  r reboot followi
6ab0: 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f  ng a crash or po
6ac0: 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e  wer loss, the on
6ad0: 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a  ly bytes in a.**
6ae0: 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20   file that were 
6af0: 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61  written at the a
6b00: 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c  pplication level
6b10: 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e   might have chan
6b20: 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ged.** and that 
6b30: 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20  adjacent bytes, 
6b40: 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69  even bytes withi
6b50: 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f  n the same secto
6b60: 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74  r are.** guarant
6b70: 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e  eed to be unchan
6b80: 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ged.  The SQLITE
6b90: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
6ba0: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20  LE_WHEN_OPEN.** 
6bb0: 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20 74  flag indicates t
6bc0: 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f  hat a file canno
6bd0: 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68 65  t be deleted whe
6be0: 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20  n open.  The.** 
6bf0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
6c00: 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69  UTABLE flag indi
6c10: 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 66  cates that the f
6c20: 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61  ile is on.** rea
6c30: 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64  d-only media and
6c40: 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
6c50: 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65  ed even by proce
6c60: 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65  sses with.** ele
6c70: 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 65 73  vated privileges
6c80: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
6c90: 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41  TE_IOCAP_BATCH_A
6ca0: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
6cb0: 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 75 6e  eans that the un
6cc0: 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 66 69 6c 65  derlying.** file
6cd0: 73 79 73 74 65 6d 20 73 75 70 70 6f 72 74 73 20  system supports 
6ce0: 64 6f 69 6e 67 20 6d 75 6c 74 69 70 6c 65 20 77  doing multiple w
6cf0: 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  rite operations 
6d00: 61 74 6f 6d 69 63 61 6c 6c 79 20 77 68 65 6e 20  atomically when 
6d10: 74 68 6f 73 65 0a 2a 2a 20 77 72 69 74 65 20 6f  those.** write o
6d20: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 62 72  perations are br
6d30: 61 63 6b 65 74 65 64 20 62 79 20 5b 53 51 4c 49  acketed by [SQLI
6d40: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
6d50: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 61 6e 64  TOMIC_WRITE] and
6d60: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
6d70: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
6d80: 57 52 49 54 45 5d 2e 0a 2a 2f 0a 23 64 65 66 69  WRITE]..*/.#defi
6d90: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6da0: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
6db0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6dc0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6dd0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
6de0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6df0: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65  00000002.#define
6e00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6e10: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20  OMIC1K          
6e20: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
6e30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6e40: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20  OCAP_ATOMIC2K   
6e50: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6e60: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
6e70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6e80: 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC4K            
6e90: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
6ea0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6eb0: 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20  AP_ATOMIC8K     
6ec0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6ed0: 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0020.#define SQL
6ee0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6ef0: 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  16K             
6f00: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66   0x00000040.#def
6f10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6f20: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20  _ATOMIC32K      
6f30: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6f40: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  80.#define SQLIT
6f50: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
6f60: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6f70: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e  x00000100.#defin
6f80: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6f90: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20  AFE_APPEND      
6fa0: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
6fb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6fc0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6fe0: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20  0000400.#define 
6ff0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
7000: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
7010: 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23  EN  0x00000800.#
7020: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7030: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
7040: 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30  ERWRITE    0x000
7050: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
7060: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
7070: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  ABLE            
7080: 20 20 30 78 30 30 30 30 32 30 30 30 0a 23 64 65    0x00002000.#de
7090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
70a0: 50 5f 42 41 54 43 48 5f 41 54 4f 4d 49 43 20 20  P_BATCH_ATOMIC  
70b0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 34           0x00004
70c0: 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  000../*.** CAPI3
70d0: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
70e0: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
70f0: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
7100: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
7110: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
7120: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
7130: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
7140: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
7150: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
7160: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
7170: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
7180: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
7190: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
71a0: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
71b0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
71c0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
71d0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
71e0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
71f0: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
7200: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
7210: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
7220: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7230: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
7240: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
7250: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
7260: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
7270: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
7280: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
7290: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
72a0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
72b0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
72c0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
72d0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
72e0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
72f0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
7300: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
7310: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
7320: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
7330: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
7340: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
7350: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
7360: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
7370: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
7380: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
7390: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
73a0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
73b0: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
73c0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
73d0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
73e0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
73f0: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
7400: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
7410: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
7420: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
7430: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
7440: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
7450: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
7460: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
7470: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
7480: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
7490: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e  nc()..**.** Do n
74a0: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53  ot confuse the S
74b0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
74c0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
74d0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20  C_FULL flags.** 
74e0: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41  with the [PRAGMA
74f0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f   synchronous]=NO
7500: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41  RMAL and [PRAGMA
7510: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55   synchronous]=FU
7520: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20  LL.** settings. 
7530: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75   The [synchronou
7540: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d  s pragma] determ
7550: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20  ines when calls 
7560: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20  to the.** xSync 
7570: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72  VFS method occur
7580: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69   and applies uni
7590: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c  formly across al
75a0: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20  l platforms..** 
75b0: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
75c0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
75d0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
75e0: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a  s determine how.
75f0: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20  ** energetic or 
7600: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63  rigorous or forc
7610: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70  eful the sync op
7620: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64  erations are and
7630: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20  .** only make a 
7640: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61  difference on Ma
7650: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65  c OSX for the de
7660: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64  fault SQLite cod
7670: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72  e..** (Third-par
7680: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ty VFS implement
7690: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73  ations might als
76a0: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  o make the disti
76b0: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
76c0: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  n SQLITE_SYNC_NO
76d0: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
76e0: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61  SYNC_FULL, but a
76f0: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72  mong the.** oper
7700: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61  ating systems na
7710: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64  tively supported
7720: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79   by SQLite, only
7730: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65   Mac OSX.** care
7740: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66  s about the diff
7750: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66  erence.).*/.#def
7760: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
7770: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
7780: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
7790: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
77a0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
77b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
77c0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
77d0: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
77e0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
77f0: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
7800: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41  e Handle.**.** A
7810: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
7820: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
7830: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
7840: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  in the .** [sqli
7850: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74  te3_vfs | OS int
7860: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20  erface layer].  
7870: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
7880: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65  terface.** imple
7890: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
78a0: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
78b0: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
78c0: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
78d0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
78e0: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
78f0: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
7900: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
7910: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
7920: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7930: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
7940: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
7950: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
7960: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
7970: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
7980: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
7990: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
79a0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
79b0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
79c0: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
79d0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
79e0: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
79f0: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
7a00: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
7a10: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
7a20: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
7a30: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
7a40: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
7a50: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
7a60: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
7a70: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7a80: 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  n] method popula
7a90: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
7aa0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
7ab0: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
7ac0: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
7ad0: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
7ae0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
7af0: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
7b00: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
7b10: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
7b20: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
7b30: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
7b40: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
7b50: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
7b60: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
7b70: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
7b80: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
7b90: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7ba0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
7bb0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7bc0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73  .xOpen] method s
7bd0: 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ets the sqlite3_
7be0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7bf0: 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e  ement .** to a n
7c00: 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
7c10: 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
7c20: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c  3_io_methods.xCl
7c30: 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61  ose method.** ma
7c40: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65  y be invoked eve
7c50: 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n if the [sqlite
7c60: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70  3_vfs.xOpen] rep
7c70: 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61  orted that it fa
7c80: 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e  iled.  The.** on
7c90: 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e  ly way to preven
7ca0: 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f  t a call to xClo
7cb0: 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  se following a f
7cc0: 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76  ailed [sqlite3_v
7cd0: 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20  fs.xOpen].** is 
7ce0: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
7cf0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73  _vfs.xOpen] to s
7d00: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
7d10: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
7d20: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e  ment.** to NULL.
7d30: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
7d40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
7d50: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
7d60: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
7d70: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
7d80: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
7d90: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
7da0: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
7db0: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20  fsync()..** The 
7dc0: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
7dd0: 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c   a Mac OS X styl
7de0: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
7df0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41   [SQLITE_SYNC_DA
7e00: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20  TAONLY].** flag 
7e10: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
7e20: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
7e30: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
7e40: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64   the file.** and
7e50: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
7e60: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65  eeds to be synce
7e70: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  d..**.** The int
7e80: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
7e90: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
7ea0: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
7eb0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
7ec0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
7ed0: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
7ee0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
7ef0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7f00: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
7f10: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7f20: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
7f30: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
7f40: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
7f50: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
7f60: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
7f70: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
7f80: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
7f90: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68   the lock..** Th
7fa0: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
7fb0: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68  Lock() method ch
7fc0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79  ecks whether any
7fd0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
7fe0: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20  tion,.** either 
7ff0: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  in this process 
8000: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
8010: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
8020: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c  ding a RESERVED,
8030: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
8040: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
8050: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
8060: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
8070: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
8080: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
8090: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
80a0: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
80b0: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
80c0: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
80d0: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
80e0: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
80f0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
8100: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
8110: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
8120: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
8130: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8140: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
8150: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
8160: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a  rgument is an.**
8170: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
8180: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
8190: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
81a0: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64  c pointer intend
81b0: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74  ed to.** point t
81c0: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
81d0: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
81e0: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
81f0: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
8200: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
8210: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
8220: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
8230: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
8240: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
8250: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
8260: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
8270: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
8280: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
8290: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
82a0: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
82b0: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
82c0: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
82d0: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
82e0: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
82f0: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
8300: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
8310: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c  core reserves al
8320: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  l opcodes less t
8330: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
8340: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66  own use..** A [f
8350: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
8360: 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70  des | list of op
8370: 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e  codes] less than
8380: 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c   100 is availabl
8390: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
83a0: 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  ns that define a
83b0: 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e   custom xFileCon
83c0: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75  trol method shou
83d0: 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a  ld use opcodes.*
83e0: 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  * greater than 1
83f0: 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66  00 to avoid conf
8400: 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c  licts.  VFS impl
8410: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
8420: 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
8430: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66  LITE_NOTFOUND] f
8440: 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  or file control 
8450: 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65  opcodes that the
8460: 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f  y do not.** reco
8470: 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  gnize..**.** The
8480: 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d   xSectorSize() m
8490: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68  ethod returns th
84a0: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66  e sector size of
84b0: 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74   the.** device t
84c0: 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68  hat underlies th
84d0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63  e file.  The sec
84e0: 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a  tor size is the.
84f0: 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65  ** minimum write
8500: 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72   that can be per
8510: 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64  formed without d
8520: 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68  isturbing.** oth
8530: 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  er bytes in the 
8540: 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69  file.  The xDevi
8550: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
8560: 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  s().** method re
8570: 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74  turns a bit vect
8580: 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65  or describing be
8590: 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a  haviors of the.*
85a0: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76  * underlying dev
85b0: 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ice:.**.** <ul>.
85c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
85d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a  IOCAP_ATOMIC].**
85e0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
85f0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a  CAP_ATOMIC512].*
8600: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8610: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a  OCAP_ATOMIC1K].*
8620: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8630: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a  OCAP_ATOMIC2K].*
8640: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8650: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a  OCAP_ATOMIC4K].*
8660: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8670: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a  OCAP_ATOMIC8K].*
8680: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8690: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a  OCAP_ATOMIC16K].
86a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
86b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d  IOCAP_ATOMIC32K]
86c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
86d0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
86e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
86f0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
8700: 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  END].** <li> [SQ
8710: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8720: 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  NTIAL].** <li> [
8730: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
8740: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
8750: 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  EN].** <li> [SQL
8760: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
8770: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 0a 2a  AFE_OVERWRITE].*
8780: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8790: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 0a  OCAP_IMMUTABLE].
87a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
87b0: 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d  IOCAP_BATCH_ATOM
87c0: 49 43 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  IC].** </ul>.**.
87d0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
87e0: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
87f0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
8800: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
8810: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
8820: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
8830: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
8840: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
8850: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
8860: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
8870: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
8880: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
8890: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
88a0: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
88b0: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
88c0: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
88d0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
88e0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
88f0: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
8900: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
8910: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
8920: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
8930: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
8940: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
8950: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
8960: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
8970: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
8980: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
8990: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
89a0: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
89b0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
89c0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
89d0: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
89e0: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
89f0: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
8a00: 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  xWrite()..**.** 
8a10: 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72  If xRead() retur
8a20: 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ns SQLITE_IOERR_
8a30: 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75  SHORT_READ it mu
8a40: 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20  st also fill.** 
8a50: 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f  in the unread po
8a60: 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75  rtions of the bu
8a70: 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e  ffer with zeros.
8a80: 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20    A VFS that.** 
8a90: 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69  fails to zero-fi
8aa0: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d  ll short reads m
8ab0: 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72  ight seem to wor
8ac0: 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  k.  However,.** 
8ad0: 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d  failure to zero-
8ae0: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
8af0: 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79   will eventually
8b00: 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61   lead to.** data
8b10: 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e  base corruption.
8b20: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
8b30: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
8b40: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f  thods sqlite3_io
8b50: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
8b60: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
8b70: 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ods {.  int iVer
8b80: 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
8b90: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69  lose)(sqlite3_fi
8ba0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  le*);.  int (*xR
8bb0: 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ead)(sqlite3_fil
8bc0: 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  e*, void*, int i
8bd0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
8be0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
8bf0: 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74   (*xWrite)(sqlit
8c00: 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20  e3_file*, const 
8c10: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
8c20: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8c30: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
8c40: 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65  Truncate)(sqlite
8c50: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
8c60: 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20  _int64 size);.  
8c70: 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
8c80: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8c90: 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  flags);.  int (*
8ca0: 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74  xFileSize)(sqlit
8cb0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8cc0: 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b  3_int64 *pSize);
8cd0: 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28  .  int (*xLock)(
8ce0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8cf0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  nt);.  int (*xUn
8d00: 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  lock)(sqlite3_fi
8d10: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8d20: 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65   (*xCheckReserve
8d30: 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  dLock)(sqlite3_f
8d40: 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f  ile*, int *pResO
8d50: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ut);.  int (*xFi
8d60: 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74  leControl)(sqlit
8d70: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70  e3_file*, int op
8d80: 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20  , void *pArg);. 
8d90: 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69   int (*xSectorSi
8da0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
8db0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76  *);.  int (*xDev
8dc0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
8dd0: 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  cs)(sqlite3_file
8de0: 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *);.  /* Methods
8df0: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
8e00: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a   for version 1 *
8e10: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61  /.  int (*xShmMa
8e20: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8e30: 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70  , int iPg, int p
8e40: 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76  gsz, int, void v
8e50: 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e  olatile**);.  in
8e60: 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71  t (*xShmLock)(sq
8e70: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8e80: 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20   offset, int n, 
8e90: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f  int flags);.  vo
8ea0: 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72  id (*xShmBarrier
8eb0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8ec0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e  ;.  int (*xShmUn
8ed0: 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  map)(sqlite3_fil
8ee0: 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c  e*, int deleteFl
8ef0: 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  ag);.  /* Method
8f00: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
8f10: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20  d for version 2 
8f20: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63  */.  int (*xFetc
8f30: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
8f40: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8f50: 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c  iOfst, int iAmt,
8f60: 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69   void **pp);.  i
8f70: 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73  nt (*xUnfetch)(s
8f80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8f90: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8fa0: 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f  t, void *p);.  /
8fb0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8fc0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8fd0: 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20  rsion 3 */.  /* 
8fe0: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
8ff0: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
9000: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
9010: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
9020: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
9030: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
9040: 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  Opcodes.** KEYWO
9050: 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72  RDS: {file contr
9060: 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c  ol opcodes} {fil
9070: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
9080: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  }.**.** These in
9090: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
90a0: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
90b0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
90c0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
90d0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
90e0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
90f0: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
9100: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9110: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
9120: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
9130: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9140: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a  L_LOCKSTATE]].**
9150: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9160: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70  TL_LOCKSTATE] op
9170: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
9180: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
9190: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
91a0: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
91b0: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72  rol method to wr
91c0: 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20  ite the current 
91d0: 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20  state of.** the 
91e0: 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51  lock (one of [SQ
91f0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
9200: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
9210: 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ARED],.** [SQLIT
9220: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
9230: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  , [SQLITE_LOCK_P
9240: 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c  ENDING], or [SQL
9250: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
9260: 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20  VE]).** into an 
9270: 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65  integer that the
9280: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70   pArg argument p
9290: 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63  oints to. This c
92a0: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
92b0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
92c0: 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20  ing and is only 
92d0: 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e 20 74  available when t
92e0: 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  he SQLITE_TEST.*
92f0: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
9300: 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
9310: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9320: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
9330: 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  T]].** The [SQLI
9340: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
9350: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
9360: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
9370: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
9380: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
9390: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
93a0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
93b0: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
93c0: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
93d0: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
93e0: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
93f0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
9400: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
9410: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
9420: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
9430: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
9440: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
9450: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
9460: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
9470: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
9480: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
9490: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
94a0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
94b0: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
94c0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
94d0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d  NTL_CHUNK_SIZE]]
94e0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
94f0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
9500: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9510: 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74   to request that
9520: 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65   the VFS.** exte
9530: 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65  nds and truncate
9540: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
9550: 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66  ile in chunks of
9560: 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65   a size specifie
9570: 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72  d.** by the user
9580: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  . The fourth arg
9590: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
95a0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
95b0: 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69  ] should .** poi
95c0: 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  nt to an integer
95d0: 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74   (type int) cont
95e0: 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63  aining the new c
95f0: 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65  hunk-size to use
9600: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69  .** for the nomi
9610: 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  nated database. 
9620: 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62  Allocating datab
9630: 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69  ase file space i
9640: 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b  n large.** chunk
9650: 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20  s (say 1MB at a 
9660: 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63  time), may reduc
9670: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72  e file-system fr
9680: 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a  agmentation and.
9690: 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  ** improve perfo
96a0: 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73  rmance on some s
96b0: 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ystems..**.** <l
96c0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
96d0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a  _FILE_POINTER]].
96e0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
96f0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
9700: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
9710: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
9720: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
9730: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
9740: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
9750: 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
9760: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
9770: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
9780: 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e  also [SQLITE_FCN
9790: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
97a0: 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ER]..**.** <li>[
97b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f  [SQLITE_FCNTL_JO
97c0: 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a  URNAL_POINTER]].
97d0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
97e0: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
97f0: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
9800: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
9810: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
9820: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
9830: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
9840: 74 65 64 20 77 69 74 68 20 74 68 65 20 6a 6f 75  ted with the jou
9850: 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74 68 65  rnal file (eithe
9860: 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61  r.** the [rollba
9870: 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74  ck journal] or t
9880: 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61 64 20  he [write-ahead 
9890: 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61 72 74  log]) for a part
98a0: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
98b0: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
98c0: 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45  See also [SQLITE
98d0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
98e0: 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  TER]..**.** <li>
98f0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
9900: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a  YNC_OMITTED]].**
9910: 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73   No longer in us
9920: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  e..**.** <li>[[S
9930: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
9940: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9950: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70  E_FCNTL_SYNC] op
9960: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65  code is generate
9970: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
9980: 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65  SQLite and.** se
9990: 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69 6d  nt to the VFS im
99a0: 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65  mediately before
99b0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
99c0: 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  d is invoked on 
99d0: 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69  a.** database fi
99e0: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20 4f  le descriptor. O
99f0: 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63 20  r, if the xSync 
9a00: 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e  method is not in
9a10: 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 73  voked .** becaus
9a20: 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20 63  e the user has c
9a30: 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74 65  onfigured SQLite
9a40: 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d   with .** [PRAGM
9a50: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20  A synchronous | 
9a60: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
9a70: 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 6e  us=OFF] it is in
9a80: 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 0a  voked in place .
9a90: 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63 20  ** of the xSync 
9aa0: 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20  method. In most 
9ab0: 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e 74  cases, the point
9ac0: 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  er argument pass
9ad0: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 20  ed with.** this 
9ae0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
9af0: 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69  NULL. However, i
9b00: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
9b10: 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79 6e  ile is being syn
9b20: 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  ced.** as part o
9b30: 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 61  f a multi-databa
9b40: 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61  se commit, the a
9b50: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
9b60: 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  o a nul-terminat
9b70: 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ed.** string con
9b80: 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61 6e  taining the tran
9b90: 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d  sactions master-
9ba0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d  journal file nam
9bb0: 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a 2a  e. VFSes that .*
9bc0: 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  * do not need th
9bd0: 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64  is signal should
9be0: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
9bf0: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70   this opcode. Ap
9c00: 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73  plications .** s
9c10: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b  hould not call [
9c20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9c30: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
9c40: 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e  s opcode as doin
9c50: 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73  g so may .** dis
9c60: 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69  rupt the operati
9c70: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
9c80: 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74  lized VFSes that
9c90: 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20   do require it. 
9ca0: 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51   .**.** <li>[[SQ
9cb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
9cc0: 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20  T_PHASETWO]].** 
9cd0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9ce0: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
9cf0: 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e  O] opcode is gen
9d00: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c  erated internall
9d10: 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  y by SQLite.** a
9d20: 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56  nd sent to the V
9d30: 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e 73  FS after a trans
9d40: 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e 20  action has been 
9d50: 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 69  committed immedi
9d60: 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66  ately.** but bef
9d70: 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ore the database
9d80: 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46   is unlocked. VF
9d90: 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20  Ses that do not 
9da0: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
9db0: 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  .** should silen
9dc0: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
9dd0: 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74  opcode. Applicat
9de0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ions should not 
9df0: 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
9e00: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9e10: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
9e20: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
9e30: 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a 2a  y disrupt the .*
9e40: 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  * operation of t
9e50: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
9e60: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
9e70: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
9e80: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9e90: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
9ea0: 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  RY]].** ^The [SQ
9eb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
9ec0: 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64  _AV_RETRY] opcod
9ed0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  e is used to con
9ee0: 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63  figure automatic
9ef0: 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73  .** retry counts
9f00: 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66   and intervals f
9f10: 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20  or certain disk 
9f20: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66  I/O operations f
9f30: 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  or the.** window
9f40: 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  s [VFS] in order
9f50: 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75   to provide robu
9f60: 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72  stness in the pr
9f70: 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74  esence of.** ant
9f80: 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73  i-virus programs
9f90: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
9fa0: 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77  he windows VFS w
9fb0: 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72  ill retry file r
9fc0: 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69  ead,.** file wri
9fd0: 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c  te, and file del
9fe0: 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75  ete operations u
9ff0: 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77  p to 10 times, w
a000: 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f  ith a delay.** o
a010: 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  f 25 millisecond
a020: 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72  s before the fir
a030: 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74  st retry and wit
a040: 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72  h the delay incr
a050: 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20  easing.** by an 
a060: 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69  additional 25 mi
a070: 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20  lliseconds with 
a080: 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20  each subsequent 
a090: 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20  retry.  This.** 
a0a0: 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68  opcode allows th
a0b0: 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28  ese two values (
a0c0: 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32  10 retries and 2
a0d0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  5 milliseconds o
a0e0: 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62  f delay).** to b
a0f0: 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65  e adjusted.  The
a100: 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e   values are chan
a110: 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61  ged for all data
a120: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
a130: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73  .** within the s
a140: 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68  ame process.  Th
a150: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
a160: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72  pointer to an ar
a170: 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e  ray of two.** in
a180: 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65  tegers where the
a190: 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69   first integer i
a1a0: 73 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  s the new retry 
a1b0: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
a1c0: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
a1d0: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
a1e0: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
a1f0: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
a200: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
a210: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
a220: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
a230: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
a240: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
a250: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
a260: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
a270: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
a280: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
a290: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
a2a0: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
a2b0: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
a2c0: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
a2d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a2e0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
a2f0: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
a300: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
a310: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
a320: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
a330: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
a340: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
a350: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
a360: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
a370: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
a380: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
a390: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
a3a0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
a3b0: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
a3c0: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
a3d0: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
a3e0: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
a3f0: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
a400: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
a410: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
a420: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
a430: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
a440: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
a450: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
a460: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
a470: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
a480: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
a490: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
a4a0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
a4b0: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
a4c0: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
a4d0: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
a4e0: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
a4f0: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
a500: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
a510: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
a520: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
a530: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
a540: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
a550: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
a560: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
a570: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
a580: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
a590: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
a5a0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
a5b0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
a5c0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
a5d0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
a5e0: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
a5f0: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
a600: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
a610: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
a620: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
a630: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a640: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a650: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a660: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a670: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
a680: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
a690: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a6a0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a6b0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
a6c0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a6d0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a6e0: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
a6f0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
a700: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
a710: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
a720: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
a730: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
a740: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
a750: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
a760: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
a770: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
a780: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
a790: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
a7a0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
a7b0: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
a7c0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a7d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a7e0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a7f0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a800: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a810: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a820: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a830: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a840: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a850: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a860: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
a870: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a880: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a890: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a8a0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a8b0: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
a8c0: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
a8d0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a8e0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a8f0: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a900: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a910: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a920: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a930: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
a940: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
a950: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
a960: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
a970: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
a980: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
a990: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
a9a0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a9b0: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
a9c0: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
a9d0: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
a9e0: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
a9f0: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
aa00: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
aa10: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
aa20: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
aa30: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
aa40: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
aa50: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
aa60: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
aa70: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
aa80: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
aa90: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
aaa0: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
aab0: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
aac0: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
aad0: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
aae0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
aaf0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
ab00: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
ab10: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
ab20: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
ab30: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
ab40: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
ab50: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
ab60: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
ab70: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
ab80: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
ab90: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
aba0: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
abb0: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
abc0: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
abd0: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
abe0: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
abf0: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
ac00: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
ac10: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
ac20: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
ac30: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
ac40: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
ac50: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
ac60: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
ac70: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
ac80: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
ac90: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
aca0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
acb0: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
acc0: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
acd0: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
ace0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
acf0: 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e  S_POINTER]].** ^
ad00: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ad10: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20 6f  L_VFS_POINTER] o
ad20: 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20 70 6f  pcode finds a po
ad30: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70  inter to the top
ad40: 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65 73  -level.** [VFSes
ad50: 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 75  ] currently in u
ad60: 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d  se.  ^(The argum
ad70: 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c 69  ent X in.** sqli
ad80: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
ad90: 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54 4c  (db,SQLITE_FCNTL
ada0: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29 20  _VFS_POINTER,X) 
adb0: 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74 79  must be.** of ty
adc0: 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 66 73  pe "[sqlite3_vfs
add0: 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70 63  ] **".  This opc
ade0: 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20 2a 58  odes will set *X
adf0: 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65 72  .** to a pointer
ae00: 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65   to the top-leve
ae10: 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65  l VFS.)^.** ^Whe
ae20: 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75 6c 74  n there are mult
ae30: 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73 20 69  iple VFS shims i
ae40: 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74 68 69  n the stack, thi
ae50: 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 74  s opcode finds t
ae60: 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73 74  he.** upper-most
ae70: 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a   shim only..**.*
ae80: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ae90: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a  CNTL_PRAGMA]].**
aea0: 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52   ^Whenever a [PR
aeb0: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20  AGMA] statement 
aec0: 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53  is parsed, an [S
aed0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
aee0: 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  MA] .** file con
aef0: 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20  trol is sent to 
af00: 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65  the open [sqlite
af10: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63  3_file] object c
af20: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
af30: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
af40: 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68  file to which th
af50: 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  e pragma stateme
af60: 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20  nt refers. ^The 
af70: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
af80: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
af90: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
afa0: 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61  ntrol is an arra
afb0: 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73  y of.** pointers
afc0: 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61   to strings (cha
afd0: 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68  r**) in which th
afe0: 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74  e second element
aff0: 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a   of the array.**
b000: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
b010: 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74  the pragma and t
b020: 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74  he third element
b030: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
b040: 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d   to the.** pragm
b050: 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  a or NULL if the
b060: 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61   pragma has no a
b070: 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68  rgument.  ^The h
b080: 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a  andler for an.**
b090: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
b0a0: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
b0b0: 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c  rol can optional
b0c0: 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73  ly make the firs
b0d0: 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20  t element.** of 
b0e0: 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d  the char** argum
b0f0: 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  ent point to a s
b100: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66  tring obtained f
b110: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  rom [sqlite3_mpr
b120: 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68  intf()].** or th
b130: 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64  e equivalent and
b140: 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c   that string wil
b150: 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73  l become the res
b160: 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ult of the pragm
b170: 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f  a or.** the erro
b180: 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65  r message if the
b190: 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e   pragma fails. ^
b1a0: 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
b1b0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
b1c0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
b1d0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  urns [SQLITE_NOT
b1e0: 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72  FOUND], then nor
b1f0: 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d  mal .** [PRAGMA]
b200: 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74   processing cont
b210: 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20  inues.  ^If the 
b220: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b230: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
b240: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
b250: 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20  QLITE_OK], then 
b260: 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d  the parser assum
b270: 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56  es that the.** V
b280: 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74  FS has handled t
b290: 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66  he PRAGMA itself
b2a0: 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20   and the parser 
b2b0: 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f  generates a no-o
b2c0: 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  p.** prepared st
b2d0: 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c  atement if resul
b2e0: 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c  t string is NULL
b2f0: 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e  , or that return
b300: 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
b310: 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67  he result string
b320: 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   if the string i
b330: 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e  s non-NULL..** ^
b340: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
b350: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
b360: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
b370: 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20  s.** any result 
b380: 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20  code other than 
b390: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b  [SQLITE_OK] or [
b3a0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
b3b0: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
b3c0: 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63  that the VFS enc
b3d0: 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f  ountered an erro
b3e0: 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67  r while handling
b3f0: 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e   the [PRAGMA] an
b400: 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61  d the.** compila
b410: 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47  tion of the PRAG
b420: 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  MA fails with an
b430: 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53   error.  ^The [S
b440: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b450: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
b460: 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68  rol occurs at th
b470: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70  e beginning of p
b480: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
b490: 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a  analysis and so.
b4a0: 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f  ** it is able to
b4b0: 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d   override built-
b4c0: 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74  in [PRAGMA] stat
b4d0: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ements..**.** <l
b4e0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b4f0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a  _BUSYHANDLER]].*
b500: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
b510: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
b520: 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  ].** file-contro
b530: 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  l may be invoked
b540: 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68   by SQLite on th
b550: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
b560: 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c  handle.** shortl
b570: 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70  y after it is op
b580: 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  ened in order to
b590: 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f   provide a custo
b5a0: 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73  m VFS with acces
b5b0: 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e  s.** to the conn
b5c0: 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e  ections busy-han
b5d0: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54  dler callback. T
b5e0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  he argument is o
b5f0: 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29  f type (void **)
b600: 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f  .** - an array o
b610: 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76  f two (void *) v
b620: 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74  alues. The first
b630: 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c   (void *) actual
b640: 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20  ly points.** to 
b650: 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
b660: 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64  pe (int (*)(void
b670: 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74   *)). In order t
b680: 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e  o invoke the con
b690: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79  nections.** busy
b6a0: 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66  -handler, this f
b6b0: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  unction should b
b6c0: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
b6d0: 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20  he second (void 
b6e0: 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72  *) in.** the arr
b6f0: 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61  ay as the only a
b700: 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72  rgument. If it r
b710: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
b720: 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74   then the operat
b730: 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
b740: 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20   retried. If it 
b750: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
b760: 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f  e custom VFS sho
b770: 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a  uld abandon the.
b780: 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  ** current opera
b790: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tion..**.** <li>
b7a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
b7b0: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a  EMPFILENAME]].**
b7c0: 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61   ^Application ca
b7d0: 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51  n invoke the [SQ
b7e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b7f0: 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f  ILENAME] file-co
b800: 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65  ntrol.** to have
b810: 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65   SQLite generate
b820: 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20   a.** temporary 
b830: 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74  filename using t
b840: 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
b850: 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77  m that is follow
b860: 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a  ed to generate.*
b870: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
b880: 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74  names for TEMP t
b890: 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20  ables and other 
b8a0: 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20  internal uses.  
b8b0: 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  The.** argument 
b8c0: 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72  should be a char
b8d0: 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
b8e0: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
b8f0: 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69   filename.** wri
b900: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
b910: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
b920: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
b930: 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73  ].  The caller s
b940: 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20  hould.** invoke 
b950: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
b960: 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74   on the result t
b970: 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79  o avoid a memory
b980: 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   leak..**.** <li
b990: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b9a0: 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  MMAP_SIZE]].** T
b9b0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b9c0: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
b9d0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
b9e0: 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74   to query or set
b9f0: 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20   the.** maximum 
ba00: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
ba10: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65  that will be use
ba20: 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70  d for memory-map
ba30: 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20  ped I/O..** The 
ba40: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
ba50: 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65  inter to a value
ba60: 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33   of type sqlite3
ba70: 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69  _int64 that.** i
ba80: 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61  s an advisory ma
ba90: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
baa0: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
bab0: 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e  e to memory map.
bac0: 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72    The.** pointer
bad0: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
bae0: 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c  with the old val
baf0: 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69  ue.  The limit i
bb00: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66  s not changed if
bb10: 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72  .** the value or
bb20: 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64  iginally pointed
bb30: 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c   to is negative,
bb40: 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72   and so the curr
bb50: 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61  ent limit .** ca
bb60: 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20  n be queried by 
bb70: 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69  passing in a poi
bb80: 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69  nter to a negati
bb90: 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73  ve number.  This
bba0: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
bbb0: 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
bbc0: 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  lly to implement
bbd0: 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
bbe0: 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ze]..**.** <li>[
bbf0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
bc00: 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ACE]].** The [SQ
bc10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
bc20: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70  ] file control p
bc30: 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79  rovides advisory
bc40: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
bc50: 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74  to the VFS about
bc60: 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72   what the higher
bc70: 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53   layers of the S
bc80: 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20  QLite stack are 
bc90: 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66  doing..** This f
bca0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
bcb0: 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20  sed by some VFS 
bcc0: 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67  activity tracing
bcd0: 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65   [shims]..** The
bce0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a   argument is a z
bcf0: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
bd00: 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c  tring.  Higher l
bd10: 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20  ayers in the.** 
bd20: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79  SQLite stack may
bd30: 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e   generate instan
bd40: 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ces of this file
bd50: 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74   control if.** t
bd60: 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46  he [SQLITE_USE_F
bd70: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70  CNTL_TRACE] comp
bd80: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
bd90: 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
bda0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
bdb0: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d  CNTL_HAS_MOVED]]
bdc0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
bdd0: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
bde0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e   file control in
bdf0: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
be00: 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f  ument as a.** po
be10: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
be20: 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65  ger and it write
be30: 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f  s a boolean into
be40: 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65   that integer de
be50: 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68  pending.** on wh
be60: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
be70: 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72   file has been r
be80: 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f  enamed, moved, o
be90: 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20  r deleted since 
bea0: 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20  it.** was first 
beb0: 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opened..**.** <l
bec0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bed0: 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c  _WIN32_GET_HANDL
bee0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
bef0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47  TE_FCNTL_WIN32_G
bf00: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64  ET_HANDLE] opcod
bf10: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
bf20: 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a 2a 20 75   obtain the.** u
bf30: 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74 69 76 65  nderlying native
bf40: 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 73 73   file handle ass
bf50: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 66  ociated with a f
bf60: 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20 54 68 69  ile handle.  Thi
bf70: 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f  s file.** contro
bf80: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73  l interprets its
bf90: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 20 70   argument as a p
bfa0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 61 74 69  ointer to a nati
bfb0: 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61  ve file handle a
bfc0: 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20 74 68 65  nd.** writes the
bfd0: 20 72 65 73 75 6c 74 69 6e 67 20 76 61 6c 75 65   resulting value
bfe0: 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c   there..**.** <l
bff0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c000: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
c010: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
c020: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
c030: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64  ET_HANDLE] opcod
c040: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
c050: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
c060: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
c070: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
c080: 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20   method to swap 
c090: 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  the file handle 
c0a0: 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20  with the one.** 
c0b0: 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
c0c0: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e  e pArg argument.
c0d0: 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74    This capabilit
c0e0: 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  y is used during
c0f0: 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20   testing.** and 
c100: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
c110: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
c120: 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64  SQLITE_TEST is d
c130: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  efined..**.** <l
c140: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c150: 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20  _WAL_BLOCK]].** 
c160: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c170: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20  L_WAL_BLOCK] is 
c180: 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20  a signal to the 
c190: 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 69  VFS layer that i
c1a0: 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64  t might.** be ad
c1b0: 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c  vantageous to bl
c1c0: 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20  ock on the next 
c1d0: 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20  WAL lock if the 
c1e0: 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65  lock is not imme
c1f0: 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c  diately.** avail
c200: 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73  able.  The WAL s
c210: 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 20  ubsystem issues 
c220: 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69  this signal duri
c230: 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75  ng rare.** circu
c240: 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65  mstances in orde
c250: 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c  r to fix a probl
c260: 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 79  em with priority
c270: 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41   inversion..** A
c280: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
c290: 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20  ld <em>not</em> 
c2a0: 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  use this file-co
c2b0: 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ntrol..**.** <li
c2c0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
c2d0: 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20  ZIPVFS]].** The 
c2e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49  [SQLITE_FCNTL_ZI
c2f0: 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20  PVFS] opcode is 
c300: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a  implemented by z
c310: 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20  ipvfs only. All 
c320: 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f  other.** VFS sho
c330: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54  uld return SQLIT
c340: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74  E_NOTFOUND for t
c350: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a  his opcode..**.*
c360: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c370: 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68  CNTL_RBU]].** Th
c380: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
c390: 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  RBU] opcode is i
c3a0: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68  mplemented by th
c3b0: 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75 73  e special VFS us
c3c0: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 55  ed by.** the RBU
c3d0: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e   extension only.
c3e0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20    All other VFS 
c3f0: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51  should return SQ
c400: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f  LITE_NOTFOUND fo
c410: 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65  r.** this opcode
c420: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
c430: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
c440: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
c450: 5d 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 51 4c  ].** If the [SQL
c460: 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f  ITE_FCNTL_BEGIN_
c470: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70  ATOMIC_WRITE] op
c480: 63 6f 64 65 20 72 65 74 75 72 6e 73 20 53 51 4c  code returns SQL
c490: 49 54 45 5f 4f 4b 2c 20 74 68 65 6e 0a 2a 2a 20  ITE_OK, then.** 
c4a0: 74 68 65 20 66 69 6c 65 20 64 65 73 63 72 69 70  the file descrip
c4b0: 74 6f 72 20 69 73 20 70 6c 61 63 65 64 20 69 6e  tor is placed in
c4c0: 20 22 62 61 74 63 68 20 77 72 69 74 65 20 6d 6f   "batch write mo
c4d0: 64 65 22 2c 20 77 68 69 63 68 0a 2a 2a 20 6d 65  de", which.** me
c4e0: 61 6e 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65  ans all subseque
c4f0: 6e 74 20 77 72 69 74 65 20 6f 70 65 72 61 74 69  nt write operati
c500: 6f 6e 73 20 77 69 6c 6c 20 62 65 20 64 65 66 65  ons will be defe
c510: 72 72 65 64 20 61 6e 64 20 64 6f 6e 65 0a 2a 2a  rred and done.**
c520: 20 61 74 6f 6d 69 63 61 6c 6c 79 20 61 74 20 74   atomically at t
c530: 68 65 20 6e 65 78 74 20 5b 53 51 4c 49 54 45 5f  he next [SQLITE_
c540: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
c550: 4d 49 43 5f 57 52 49 54 45 5d 2e 20 20 53 79 73  MIC_WRITE].  Sys
c560: 74 65 6d 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20  tems.** that do 
c570: 6e 6f 74 20 73 75 70 70 6f 72 74 20 62 61 74 63  not support batc
c580: 68 20 61 74 6f 6d 69 63 20 77 72 69 74 65 73 20  h atomic writes 
c590: 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49  will return SQLI
c5a0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 2e 0a 2a 2a 20  TE_NOTFOUND..** 
c5b0: 5e 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 73 75 63  ^Following a suc
c5c0: 63 65 73 73 66 75 6c 20 53 51 4c 49 54 45 5f 46  cessful SQLITE_F
c5d0: 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49  CNTL_BEGIN_ATOMI
c5e0: 43 5f 57 52 49 54 45 20 61 6e 64 20 70 72 69 6f  C_WRITE and prio
c5f0: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6c 6f 73  r to.** the clos
c600: 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  ing [SQLITE_FCNT
c610: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
c620: 57 52 49 54 45 5d 20 6f 72 0a 2a 2a 20 5b 53 51  WRITE] or.** [SQ
c630: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42  LITE_FCNTL_ROLLB
c640: 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  ACK_ATOMIC_WRITE
c650: 5d 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6d  ], SQLite will m
c660: 61 6b 65 0a 2a 2a 20 6e 6f 20 56 46 53 20 69 6e  ake.** no VFS in
c670: 74 65 72 66 61 63 65 20 63 61 6c 6c 73 20 6f 6e  terface calls on
c680: 20 74 68 65 20 73 61 6d 65 20 5b 73 71 6c 69 74   the same [sqlit
c690: 65 33 5f 66 69 6c 65 5d 20 66 69 6c 65 20 64 65  e3_file] file de
c6a0: 73 63 72 69 70 74 6f 72 0a 2a 2a 20 65 78 63 65  scriptor.** exce
c6b0: 70 74 20 66 6f 72 20 63 61 6c 6c 73 20 74 6f 20  pt for calls to 
c6c0: 74 68 65 20 78 57 72 69 74 65 20 6d 65 74 68 6f  the xWrite metho
c6d0: 64 20 61 6e 64 20 74 68 65 20 78 46 69 6c 65 43  d and the xFileC
c6e0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
c6f0: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 46 43   with [SQLITE_FC
c700: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 2e 0a  NTL_SIZE_HINT]..
c710: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c720: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
c730: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a  ATOMIC_WRITE]].*
c740: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c750: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49  NTL_COMMIT_ATOMI
c760: 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  C_WRITE] opcode 
c770: 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74 65  causes all write
c780: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20 73  .** operations s
c790: 69 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f 75  ince the previou
c7a0: 73 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  s successful cal
c7b0: 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  l to .** [SQLITE
c7c0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
c7d0: 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62 65  MIC_WRITE] to be
c7e0: 20 70 65 72 66 6f 72 6d 65 64 20 61 74 6f 6d 69   performed atomi
c7f0: 63 61 6c 6c 79 2e 0a 2a 2a 20 54 68 69 73 20 66  cally..** This f
c800: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
c810: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
c820: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
c830: 68 65 20 77 72 69 74 65 73 20 77 65 72 65 0a 2a  he writes were.*
c840: 2a 20 61 6c 6c 20 70 65 72 66 6f 72 6d 65 64 20  * all performed 
c850: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61 6e 64  successfully and
c860: 20 68 61 76 65 20 62 65 65 6e 20 63 6f 6d 6d 69   have been commi
c870: 74 74 65 64 20 74 6f 20 70 65 72 73 69 73 74 65  tted to persiste
c880: 6e 74 20 73 74 6f 72 61 67 65 2e 0a 2a 2a 20 5e  nt storage..** ^
c890: 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
c8a0: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
c8b0: 69 73 20 73 75 63 63 65 73 73 66 75 6c 2c 20 74  is successful, t
c8c0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
c8d0: 20 74 61 6b 65 73 0a 2a 2a 20 74 68 65 20 66 69   takes.** the fi
c8e0: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20 6f 75  le descriptor ou
c8f0: 74 20 6f 66 20 62 61 74 63 68 20 77 72 69 74 65  t of batch write
c900: 20 6d 6f 64 65 20 73 6f 20 74 68 61 74 20 61 6c   mode so that al
c910: 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  l subsequent.** 
c920: 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  write operations
c930: 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65 6e 74   are independent
c940: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
c950: 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 53  l never invoke S
c960: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
c970: 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20  IT_ATOMIC_WRITE 
c980: 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70 72 69  without.** a pri
c990: 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
c9a0: 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 46 43  ll to [SQLITE_FC
c9b0: 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43  NTL_BEGIN_ATOMIC
c9c0: 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  _WRITE]..**.** <
c9d0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
c9e0: 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49  L_ROLLBACK_ATOMI
c9f0: 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 68 65  C_WRITE]].** The
ca00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52   [SQLITE_FCNTL_R
ca10: 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57  OLLBACK_ATOMIC_W
ca20: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 63 61 75  RITE] opcode cau
ca30: 73 65 73 20 61 6c 6c 20 77 72 69 74 65 0a 2a 2a  ses all write.**
ca40: 20 6f 70 65 72 61 74 69 6f 6e 73 20 73 69 6e 63   operations sinc
ca50: 65 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  e the previous s
ca60: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
ca70: 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  o .** [SQLITE_FC
ca80: 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43  NTL_BEGIN_ATOMIC
ca90: 5f 57 52 49 54 45 5d 20 74 6f 20 62 65 20 72 6f  _WRITE] to be ro
caa0: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 5e 54  lled back..** ^T
cab0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
cac0: 20 74 61 6b 65 73 20 74 68 65 20 66 69 6c 65 20   takes the file 
cad0: 64 65 73 63 72 69 70 74 6f 72 20 6f 75 74 20 6f  descriptor out o
cae0: 66 20 62 61 74 63 68 20 77 72 69 74 65 20 6d 6f  f batch write mo
caf0: 64 65 0a 2a 2a 20 73 6f 20 74 68 61 74 20 61 6c  de.** so that al
cb00: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 77 72 69  l subsequent wri
cb10: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  te operations ar
cb20: 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 2e 0a 2a  e independent..*
cb30: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
cb40: 65 76 65 72 20 69 6e 76 6f 6b 65 20 53 51 4c 49  ever invoke SQLI
cb50: 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43  TE_FCNTL_ROLLBAC
cb60: 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 77  K_ATOMIC_WRITE w
cb70: 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70 72 69 6f  ithout.** a prio
cb80: 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
cb90: 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e  l to [SQLITE_FCN
cba0: 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f  TL_BEGIN_ATOMIC_
cbb0: 57 52 49 54 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  WRITE]..** </ul>
cbc0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
cbd0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
cbe0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
cbf0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
cc00: 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b  E_FCNTL_GET_LOCK
cc10: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
cc20: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
cc30: 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50  _FCNTL_SET_LOCKP
cc40: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 33  ROXYFILE       3
cc50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cc60: 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f  FCNTL_LAST_ERRNO
cc70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a                4.
cc80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
cc90: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20  CNTL_SIZE_HINT  
cca0: 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
ccb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ccc0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20  NTL_CHUNK_SIZE  
ccd0: 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
cce0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ccf0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20  TL_FILE_POINTER 
cd00: 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
cd10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
cd20: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20  L_SYNC_OMITTED  
cd30: 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66            8.#def
cd40: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
cd50: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20  _WIN32_AV_RETRY 
cd60: 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
cd70: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
cd80: 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20  PERSIST_WAL     
cd90: 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e         10.#defin
cda0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  e SQLITE_FCNTL_O
cdb0: 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20  VERWRITE        
cdc0: 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65        11.#define
cdd0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46   SQLITE_FCNTL_VF
cde0: 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  SNAME           
cdf0: 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20       12.#define 
ce00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
ce10: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
ce20: 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53      13.#define S
ce30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
ce40: 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
ce50: 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51     14.#define SQ
ce60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
ce70: 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20  ANDLER          
ce80: 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c    15.#define SQL
ce90: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
cea0: 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  LENAME          
ceb0: 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   16.#define SQLI
cec0: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
ced0: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
cee0: 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  18.#define SQLIT
cef0: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20  E_FCNTL_TRACE   
cf00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
cf10: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
cf20: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
cf30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
cf40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cf50: 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20  FCNTL_SYNC      
cf60: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 0a               21.
cf70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
cf80: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
cf90: 45 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23  ETWO        22.#
cfa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
cfb0: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41  NTL_WIN32_SET_HA
cfc0: 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64  NDLE       23.#d
cfd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
cfe0: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20  TL_WAL_BLOCK    
cff0: 20 20 20 20 20 20 20 20 20 20 32 34 0a 23 64 65            24.#de
d000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d010: 4c 5f 5a 49 50 56 46 53 20 20 20 20 20 20 20 20  L_ZIPVFS        
d020: 20 20 20 20 20 20 20 20 20 32 35 0a 23 64 65 66           25.#def
d030: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d040: 5f 52 42 55 20 20 20 20 20 20 20 20 20 20 20 20  _RBU            
d050: 20 20 20 20 20 20 20 20 32 36 0a 23 64 65 66 69          26.#defi
d060: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d070: 56 46 53 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  VFS_POINTER     
d080: 20 20 20 20 20 20 20 32 37 0a 23 64 65 66 69 6e         27.#defin
d090: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a  e SQLITE_FCNTL_J
d0a0: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20  OURNAL_POINTER  
d0b0: 20 20 20 20 20 20 32 38 0a 23 64 65 66 69 6e 65        28.#define
d0c0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
d0d0: 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 20 20  N32_GET_HANDLE  
d0e0: 20 20 20 20 20 32 39 0a 23 64 65 66 69 6e 65 20       29.#define 
d0f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 44 42  SQLITE_FCNTL_PDB
d100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d110: 20 20 20 20 33 30 0a 23 64 65 66 69 6e 65 20 53      30.#define S
d120: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
d130: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20  N_ATOMIC_WRITE  
d140: 20 20 20 33 31 0a 23 64 65 66 69 6e 65 20 53 51     31.#define SQ
d150: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
d160: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20  T_ATOMIC_WRITE  
d170: 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    32.#define SQL
d180: 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41  ITE_FCNTL_ROLLBA
d190: 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20  CK_ATOMIC_WRITE 
d1a0: 20 33 33 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74   33../* deprecat
d1b0: 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66  ed names */.#def
d1c0: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c  ine SQLITE_GET_L
d1d0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
d1e0: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47    SQLITE_FCNTL_G
d1f0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
d200: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d210: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
d220: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43  E      SQLITE_FC
d230: 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_SET_LOCKPROX
d240: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51  YFILE.#define SQ
d250: 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  LITE_LAST_ERRNO 
d260: 20 20 20 20 20 20 20 20 20 20 20 20 53 51 4c 49              SQLI
d270: 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52  TE_FCNTL_LAST_ER
d280: 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  RNO.../*.** CAPI
d290: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
d2a0: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  le.**.** The mut
d2b0: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
d2c0: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
d2d0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
d2e0: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
d2f0: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
d300: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
d310: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
d320: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
d330: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
d340: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
d350: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
d360: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
d370: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
d380: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
d390: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
d3a0: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
d3b0: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
d3c0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
d3d0: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
d3e0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
d3f0: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
d400: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
d410: 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64  * CAPI3REF: Load
d420: 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 54  able Extension T
d430: 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69  hunk.**.** A poi
d440: 6e 74 65 72 20 74 6f 20 74 68 65 20 6f 70 61 71  nter to the opaq
d450: 75 65 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  ue sqlite3_api_r
d460: 6f 75 74 69 6e 65 73 20 73 74 72 75 63 74 75 72  outines structur
d470: 65 20 69 73 20 70 61 73 73 65 64 20 61 73 0a 2a  e is passed as.*
d480: 2a 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  * the third para
d490: 6d 65 74 65 72 20 74 6f 20 65 6e 74 72 79 20 70  meter to entry p
d4a0: 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f 61 64 61 62  oints of [loadab
d4b0: 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 5d 2e 20  le extensions]. 
d4c0: 20 54 68 69 73 0a 2a 2a 20 73 74 72 75 63 74 75   This.** structu
d4d0: 72 65 20 6d 75 73 74 20 62 65 20 74 79 70 65 64  re must be typed
d4e0: 65 66 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  efed in order to
d4f0: 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 63 6f 6d   work around com
d500: 70 69 6c 65 72 20 77 61 72 6e 69 6e 67 73 0a 2a  piler warnings.*
d510: 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c 61 74 66 6f  * on some platfo
d520: 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  rms..*/.typedef 
d530: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 61  struct sqlite3_a
d540: 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 71 6c 69  pi_routines sqli
d550: 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73  te3_api_routines
d560: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
d570: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
d580: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
d590: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
d5a0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
d5b0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
d5c0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
d5d0: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
d5e0: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
d5f0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
d600: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
d610: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
d620: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
d630: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
d640: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
d650: 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b  ".  See.** the [
d660: 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65  VFS | VFS docume
d670: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72  ntation] for fur
d680: 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ther information
d690: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ..**.** The valu
d6a0: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f  e of the iVersio
d6b0: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
d6c0: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
d6d0: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66  e larger in.** f
d6e0: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
d6f0: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
d700: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
d710: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
d720: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
d730: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
d740: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
d750: 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  sed.  Note that 
d760: 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  the structure.**
d770: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
d780: 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67  vfs object chang
d790: 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61  es in the transa
d7a0: 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ction between.**
d7b0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
d7c0: 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20  3.5.9 and 3.6.0 
d7d0: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
d7e0: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
d7f0: 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a  ot.** modified..
d800: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
d810: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
d820: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
d830: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
d840: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
d850: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
d860: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
d870: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
d880: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
d890: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
d8a0: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
d8b0: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
d8c0: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
d8d0: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
d8e0: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
d8f0: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
d900: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
d910: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
d920: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
d930: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
d940: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
d950: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
d960: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
d970: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
d980: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
d990: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
d9a0: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
d9b0: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
d9c0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
d9d0: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
d9e0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
d9f0: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
da00: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
da10: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
da20: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
da30: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
da40: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
da50: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
da60: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
da70: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
da80: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
da90: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
daa0: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
dab0: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
dac0: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
dad0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
dae0: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
daf0: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
db00: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
db10: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
db20: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
db30: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
db40: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
db50: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
db60: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
db70: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
db80: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
db90: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
dba0: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
dbb0: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
dbc0: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
dbd0: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
dbe0: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
dbf0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
dc00: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
dc10: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
dc20: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
dc30: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
dc40: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
dc50: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
dc60: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
dc70: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
dc80: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
dc90: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
dca0: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
dcb0: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
dcc0: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
dcd0: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
dce0: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c  re than.** 11 al
dcf0: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
dd00: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
dd10: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
dd20: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
dd30: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
dd40: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
dd50: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
dd60: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
dd70: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
dd80: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
dd90: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
dda0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
ddb0: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
ddc0: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
ddd0: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
dde0: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
ddf0: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
de00: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
de10: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
de20: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
de30: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
de40: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
de50: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
de60: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
de70: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
de80: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
de90: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
dea0: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
deb0: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
dec0: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
ded0: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
dee0: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
def0: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
df00: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
df10: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
df20: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
df30: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
df40: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
df50: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
df60: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
df70: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
df80: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
df90: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
dfa0: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
dfb0: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
dfc0: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
dfd0: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
dfe0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
dff0: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
e000: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
e010: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
e020: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
e030: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
e040: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
e050: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
e060: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
e070: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
e080: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
e090: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
e0a0: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
e0b0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
e0c0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
e0d0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
e0e0: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
e0f0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
e100: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
e110: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
e120: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
e130: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
e140: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
e150: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
e160: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
e170: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
e180: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
e190: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
e1a0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
e1b0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
e1c0: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
e1d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
e1e0: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
e1f0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
e200: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
e210: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
e220: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
e230: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
e240: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
e250: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
e260: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
e270: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
e280: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
e290: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
e2a0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
e2b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
e2c0: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
e2d0: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
e2e0: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
e2f0: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
e300: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
e310: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
e320: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
e330: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
e340: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
e350: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
e360: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
e370: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
e380: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
e390: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
e3a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
e3b0: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
e3c0: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
e3d0: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
e3e0: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
e3f0: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
e400: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
e410: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
e420: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
e430: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
e440: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
e450: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
e460: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
e470: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
e480: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
e490: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
e4a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
e4b0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
e4c0: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
e4d0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
e4e0: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
e4f0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
e500: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
e510: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
e520: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
e530: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
e540: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
e550: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
e560: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
e570: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
e580: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
e590: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
e5a0: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
e5b0: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
e5c0: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
e5d0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
e5e0: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
e5f0: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
e600: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
e610: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
e620: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
e630: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
e640: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
e650: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
e660: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
e670: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
e680: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
e690: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
e6a0: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
e6b0: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
e6c0: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
e6d0: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
e6e0: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
e6f0: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
e700: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
e710: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
e720: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
e730: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
e740: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
e750: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
e760: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
e770: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
e780: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
e790: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
e7a0: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
e7b0: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
e7c0: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
e7d0: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
e7e0: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
e7f0: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
e800: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
e810: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
e820: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
e830: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
e840: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
e850: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
e860: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
e870: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
e880: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
e890: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
e8a0: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
e8b0: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
e8c0: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
e8d0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
e8e0: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
e8f0: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
e900: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
e910: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
e920: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
e930: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
e940: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
e950: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
e960: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
e970: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
e980: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
e990: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
e9a0: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
e9b0: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
e9c0: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
e9d0: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
e9e0: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
e9f0: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
ea00: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
ea10: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
ea20: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
ea30: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
ea40: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
ea50: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
ea60: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
ea70: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
ea80: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
ea90: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
eaa0: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
eab0: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
eac0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
ead0: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
eae0: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
eaf0: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
eb00: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
eb10: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
eb20: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ry..**.** ^SQLit
eb30: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
eb40: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
eb50: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
eb60: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
eb70: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
eb80: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
eb90: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
eba0: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
ebb0: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
ebc0: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
ebd0: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
ebe0: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
ebf0: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
ec00: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
ec10: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
ec20: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
ec30: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
ec40: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
ec50: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
ec60: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
ec70: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
ec80: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
ec90: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
eca0: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
ecb0: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
ecc0: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
ecd0: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
ece0: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
ecf0: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65  xSleep(), xCurre
ed00: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43  ntTime(), and xC
ed10: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
ed20: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
ed30: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
ed40: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
ed50: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
ed60: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
ed70: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
ed80: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
ed90: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
eda0: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
edb0: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
edc0: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
edd0: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
ede0: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
edf0: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
ee00: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
ee10: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
ee20: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
ee30: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
ee40: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
ee50: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
ee60: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
ee70: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
ee80: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
ee90: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
eea0: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
eeb0: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78  s given.  ^The x
eec0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
eed0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
eee0: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
eef0: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
ef00: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
ef10: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69  e as.** a floati
ef20: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a  ng point value..
ef30: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  ** ^The xCurrent
ef40: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
ef50: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61  od returns, as a
ef60: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a  n integer, the J
ef70: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d  ulian.** Day Num
ef80: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62  ber multiplied b
ef90: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
efa0: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
efb0: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
efc0: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
efd0: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
efe0: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
eff0: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
f000: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
f010: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
f020: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
f030: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
f040: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
f050: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
f060: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
f070: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
f080: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
f090: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
f0a0: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
f0b0: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
f0c0: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
f0d0: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
f0e0: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
f0f0: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
f100: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
f110: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
f120: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
f130: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
f140: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
f150: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
f160: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
f170: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
f180: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
f190: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
f1a0: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
f1b0: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
f1c0: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
f1d0: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
f1e0: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
f1f0: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
f200: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
f210: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
f220: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
f230: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
f240: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
f250: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
f260: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
f270: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
f280: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
f290: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
f2a0: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
f2b0: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
f2c0: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
f2d0: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
f2e0: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
f2f0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
f300: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
f310: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
f320: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
f330: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
f340: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
f350: 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
f360: 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
f370: 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
f380: 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
f390: 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
f3a0: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
f3b0: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
f3c0: 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
f3d0: 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
f3e0: 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
f3f0: 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
f400: 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
f410: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
f420: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
f430: 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
f440: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
f450: 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
f460: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
f470: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
f480: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
f490: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
f4a0: 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
f4b0: 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
f4c0: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
f4d0: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
f4e0: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
f4f0: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
f500: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
f510: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
f520: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
f530: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
f540: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
f550: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
f560: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
f570: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
f580: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
f590: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
f5a0: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
f5b0: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
f5c0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
f5d0: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
f5e0: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
f5f0: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
f600: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
f610: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
f620: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
f630: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
f640: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
f650: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
f660: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
f670: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
f680: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
f690: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
f6a0: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
f6b0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
f6c0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
f6d0: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
f6e0: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
f6f0: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
f700: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
f710: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
f720: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
f730: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
f740: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
f750: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
f760: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
f770: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
f780: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
f790: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
f7a0: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
f7b0: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
f7c0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
f7d0: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
f7e0: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
f7f0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
f800: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
f810: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
f820: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
f830: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
f840: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
f850: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
f860: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
f870: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
f880: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
f890: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
f8a0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
f8b0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
f8c0: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
f8d0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
f8e0: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
f8f0: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
f900: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
f910: 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
f920: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
f930: 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
f940: 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
f950: 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
f960: 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
f970: 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
f980: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
f990: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
f9a0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
f9b0: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
f9c0: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
f9d0: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
f9e0: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
f9f0: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
fa00: 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
fa10: 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
fa20: 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
fa30: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
fa40: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
fa50: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
fa60: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
fa70: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
fa80: 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
fa90: 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
faa0: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
fab0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
fac0: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
fad0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
fae0: 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
faf0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
fb00: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
fb10: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
fb20: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
fb30: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
fb40: 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
fb50: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
fb60: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
fb70: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
fb80: 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ed in future ver
fb90: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
fba0: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
fbb0: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
fbc0: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
fbd0: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
fbe0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
fbf0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
fc00: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
fc10: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
fc20: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
fc30: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
fc40: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
fc50: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
fc60: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
fc70: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
fc80: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
fc90: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
fca0: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
fcb0: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
fcc0: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
fcd0: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
fce0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
fcf0: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
fd00: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
fd10: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
fd20: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
fd30: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
fd40: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
fd50: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
fd60: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
fd70: 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
fd80: 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
fd90: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
fda0: 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
fdb0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
fdc0: 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
fdd0: 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
fde0: 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
fdf0: 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
fe00: 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
fe10: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
fe20: 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
fe30: 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
fe40: 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
fe50: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
fe60: 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
fe70: 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
fe80: 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
fe90: 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
fea0: 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
feb0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
fec0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
fed0: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
fee0: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
fef0: 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
ff00: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
ff10: 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
ff20: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
ff30: 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
ff40: 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
ff50: 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
ff60: 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
ff70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ff80: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
ff90: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
ffa0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
ffb0: 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
ffc0: 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
ffd0: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
ffe0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
fff0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
10000 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
10010 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
10020 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
10030 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
10040 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
10050 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
10060 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
10070 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
10080 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
10090 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
100a0 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
100b0 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
100c0 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
100d0 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
100e0 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
100f0 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
10100 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
10110 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
10120 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
10130 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
10140 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
10150 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
10160 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
10170 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
10180 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
10190 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
101a0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
101b0 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
101c0 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
101d0 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
101e0 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
101f0 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
10200 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
10210 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
10220 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
10230 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
10240 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f   given on the co
10250 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
10260 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
10270 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
10280 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
10290 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
102a0 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
102b0 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
102c0 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
102d0 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
102e0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
102f0 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
10300 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
10310 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
10320 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
10330 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
10340 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
10350 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
10360 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
10370 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
10380 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
10390 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
103a0 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
103b0 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
103c0 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
103d0 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
103e0 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
103f0 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
10400 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
10410 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
10420 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
10430 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
10440 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
10450 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
10460 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
10470 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
10480 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
10490 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
104a0 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
104b0 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
104c0 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
104d0 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
104e0 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
104f0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
10500 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
10510 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
10520 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
10530 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
10540 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
10550 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
10560 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
10570 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
10580 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
10590 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
105a0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
105b0 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
105c0 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
105d0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
105e0 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
105f0 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
10600 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
10610 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
10620 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
10630 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
10640 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
10650 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
10660 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
10670 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
10680 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
10690 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
106a0 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
106b0 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
106c0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
106d0 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
106e0 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
106f0 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
10700 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
10710 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
10720 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10730 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
10740 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
10750 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
10760 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
10770 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
10780 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
10790 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
107a0 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
107b0 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
107c0 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
107d0 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
107e0 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
107f0 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
10800 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
10810 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
10820 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
10830 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
10840 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
10850 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
10860 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10870 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
10880 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
10890 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
108a0 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
108b0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
108c0 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
108d0 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
108e0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
108f0 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
10900 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
10910 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10920 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
10930 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
10940 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
10950 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
10960 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
10970 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
10980 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
10990 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
109a0 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
109b0 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
109c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
109d0 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
109e0 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
109f0 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
10a00 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
10a10 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
10a20 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
10a30 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
10a40 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
10a50 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
10a60 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
10a70 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
10a80 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
10a90 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
10aa0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
10ab0 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
10ac0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
10ad0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
10ae0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10af0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
10b00 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
10b10 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
10b20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
10b30 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10b40 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
10b50 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
10b60 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
10b70 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
10b80 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
10b90 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
10ba0 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
10bb0 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
10bc0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
10bd0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
10be0 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
10bf0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
10c00 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
10c10 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
10c20 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
10c30 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
10c40 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
10c50 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
10c60 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
10c70 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
10c80 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
10c90 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
10ca0 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
10cb0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
10cc0 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
10cd0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
10ce0 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
10cf0 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
10d00 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
10d10 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
10d20 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
10d30 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
10d40 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
10d50 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
10d60 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
10d70 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
10d80 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
10d90 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
10da0 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
10db0 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
10dc0 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
10dd0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
10de0 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
10df0 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
10e00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
10e10 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
10e20 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
10e30 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
10e40 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
10e50 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
10e60 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
10e70 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
10e80 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
10e90 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
10ea0 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
10eb0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
10ec0 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
10ed0 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
10ee0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
10ef0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
10f00 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
10f10 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
10f20 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
10f30 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
10f40 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
10f50 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
10f60 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
10f70 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
10f80 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
10f90 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
10fa0 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
10fb0 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
10fc0 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
10fd0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
10fe0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10ff0 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
11000 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
11010 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
11020 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
11030 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
11040 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
11050 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
11060 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
11070 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
11080 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
11090 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
110a0 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
110b0 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
110c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
110d0 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
110e0 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
110f0 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
11100 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
11110 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
11120 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
11130 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
11140 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
11150 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
11160 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
11170 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
11180 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
11190 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
111a0 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
111b0 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
111c0 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
111d0 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
111e0 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
111f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
11200 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
11210 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
11220 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
11230 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
11240 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
11250 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
11260 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
11270 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
11280 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11290 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
112a0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
112b0 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
112c0 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
112d0 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
112e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
112f0 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
11300 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
11310 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
11320 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
11330 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
11340 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
11350 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
11360 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
11370 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
11380 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
11390 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
113a0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
113b0 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
113c0 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
113d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
113e0 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
113f0 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
11400 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
11410 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
11420 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
11430 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
11440 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
11450 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
11460 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
11470 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
11480 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
11490 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
114a0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
114b0 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
114c0 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
114d0 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
114e0 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
114f0 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
11500 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11510 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
11520 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
11530 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
11540 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
11550 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
11560 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
11570 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
11580 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
11590 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
115a0 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
115b0 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
115c0 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
115d0 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
115e0 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
115f0 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
11600 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
11610 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
11620 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
11630 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
11640 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
11650 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
11660 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
11670 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
11680 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
11690 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
116a0 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
116b0 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
116c0 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
116d0 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  needs..**.** <b>
116e0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
116f0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
11700 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
11710 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  . The applicatio
11720 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65  n.** must ensure
11730 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
11740 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
11750 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
11760 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
11770 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
11780 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
11790 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68  ng.</b>.**.** Th
117a0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
117b0 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
117c0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f  may only be invo
117d0 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62  ked prior to lib
117e0 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74  rary initializat
117f0 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
11800 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11810 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75  ()] or after shu
11820 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65  tdown by [sqlite
11830 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
11840 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  * ^If sqlite3_co
11850 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64  nfig() is called
11860 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
11870 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e  initialize()] an
11880 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c  d before.** [sql
11890 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
118a0 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65   then it will re
118b0 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
118c0 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77  SE..** Note, how
118d0 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69  ever, that ^sqli
118e0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
118f0 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
11900 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
11910 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
11920 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
11930 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
11940 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
11950 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
11960 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
11970 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
11980 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67  teger.** [config
11990 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20  uration option] 
119a0 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a  that determines.
119b0 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79  ** what property
119c0 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f   of SQLite is to
119d0 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20   be configured. 
119e0 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
119f0 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65  ments.** vary de
11a00 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b  pending on the [
11a10 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11a20 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
11a30 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
11a40 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f  **.** ^When a co
11a50 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11a60 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74  on is set, sqlit
11a70 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  e3_config() retu
11a80 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
11a90 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69  .** ^If the opti
11aa0 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72  on is unknown or
11ab0 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
11ac0 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74  e to set the opt
11ad0 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ion.** then this
11ae0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
11af0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72   a non-zero [err
11b00 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74  or code]..*/.int
11b10 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
11b20 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  int, ...);../*.*
11b30 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
11b40 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63  igure database c
11b50 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45  onnections.** ME
11b60 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
11b70 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
11b80 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
11b90 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
11ba0 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
11bb0 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
11bc0 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
11bd0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
11be0 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
11bf0 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
11c00 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
11c10 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
11c20 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
11c30 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
11c40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11c50 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
11c60 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
11c70 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  t)..**.** The se
11c80 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
11c90 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
11ca0 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
11cb0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  the.** [SQLITE_D
11cc0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
11cd0 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  E | configuratio
11ce0 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74  n verb] - an int
11cf0 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68  eger code .** th
11d00 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
11d10 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  t aspect of the 
11d20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11d30 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
11d40 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75  onfigured..** Su
11d50 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
11d60 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ts vary dependin
11d70 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  g on the configu
11d80 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a  ration verb..**.
11d90 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
11da0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
11db0 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
11dc0 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
11dd0 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
11de0 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
11df0 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ssful..*/.int sq
11e00 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
11e10 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
11e20 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
11e30 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
11e40 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
11e50 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  nes.**.** An ins
11e60 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
11e70 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
11e80 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
11e90 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
11ea0 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
11eb0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
11ec0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
11ed0 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
11ee0 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
11ef0 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
11f00 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
11f10 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
11f20 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
11f30 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
11f40 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
11f50 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11f60 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
11f70 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
11f80 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
11f90 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53  IG_MALLOC] or [S
11fa0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
11fb0 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79  MALLOC].  .** By
11fc0 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
11fd0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
11fe0 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
11ff0 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
12000 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
12010 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12020 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e  ]).** during con
12030 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61  figuration, an a
12040 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
12050 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
12060 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
12070 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
12080 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20  stem for SQLite 
12090 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
120a0 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63  f its.** dynamic
120b0 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
120c0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
120d0 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
120e0 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d   several [built-
120f0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
12100 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72  tors].** that ar
12110 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  e perfectly adeq
12120 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
12130 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
12140 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
12150 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
12160 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
12170 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
12180 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
12190 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
121a0 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
121b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
121c0 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
121d0 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
121e0 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
121f0 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
12200 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
12210 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
12220 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
12230 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
12240 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
12250 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
12260 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
12270 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
12280 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
12290 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
122a0 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
122b0 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
122c0 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78  * The xMalloc, x
122d0 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72  Realloc, and xFr
122e0 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
122f0 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
12300 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c   malloc(), reall
12310 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
12320 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
12330 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
12340 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  brary..** ^SQLit
12350 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
12360 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  t the second arg
12370 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61  ument to.** xRea
12380 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61  lloc is always a
12390 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
123a0 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
123b0 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a  to xRoundup..**.
123c0 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
123d0 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
123e0 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
123f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12400 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
12410 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
12420 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
12430 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
12440 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
12450 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
12460 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
12470 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
12480 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
12490 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
124a0 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
124b0 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
124c0 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
124d0 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
124e0 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
124f0 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
12500 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
12510 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
12520 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
12530 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12540 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
12550 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
12560 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
12570 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
12580 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
12590 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
125a0 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
125b0 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
125c0 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
125d0 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
125e0 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
125f0 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
12600 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
12610 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
12620 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
12630 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
12640 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
12650 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
12660 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12670 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
12680 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
12690 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
126a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
126b0 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  r.  For example,
126c0 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c  .** it might all
126d0 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72  ocate any requir
126e0 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69  e mutexes or ini
126f0 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c  tialize internal
12700 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75   data.** structu
12710 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64  res.  The xShutd
12720 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  own method is in
12730 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c  voked (indirectl
12740 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  y) by.** [sqlite
12750 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e  3_shutdown()] an
12760 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63  d should dealloc
12770 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65  ate any resource
12780 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79  s acquired.** by
12790 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70   xInit.  The pAp
127a0 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73  pData pointer is
127b0 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c   used as the onl
127c0 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  y parameter to.*
127d0 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75  * xInit and xShu
127e0 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  tdown..**.** SQL
127f0 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  ite holds the [S
12800 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
12810 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78  IC_MASTER] mutex
12820 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73   when it invokes
12830 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65  .** the xInit me
12840 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e  thod, so the xIn
12850 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e  it method need n
12860 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  ot be threadsafe
12870 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64  .  The.** xShutd
12880 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e  own method is on
12890 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b  ly called from [
128a0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
128b0 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a  ()] so it does.*
128c0 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  * not need to be
128d0 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68   threadsafe eith
128e0 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68  er.  For all oth
128f0 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69  er methods, SQLi
12900 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20  te.** holds the 
12910 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
12920 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20  ATIC_MEM] mutex 
12930 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a  as long as the.*
12940 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
12950 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66  _MEMSTATUS] conf
12960 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12970 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77   is turned on (w
12980 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79  hich.** it is by
12990 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f   default) and so
129a0 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65   the methods are
129b0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73   automatically s
129c0 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f  erialized..** Ho
129d0 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54  wever, if [SQLIT
129e0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
129f0 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c  US] is disabled,
12a00 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a   then the other.
12a10 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ** methods must 
12a20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72  be threadsafe or
12a30 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72   else make their
12a40 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74   own arrangement
12a50 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69  s for.** seriali
12a60 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  zation..**.** SQ
12a70 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
12a80 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d  invoke xInit() m
12a90 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69  ore than once wi
12aa0 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65  thout an interve
12ab0 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  ning.** call to 
12ac0 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a  xShutdown()..*/.
12ad0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
12ae0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12af0 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ds sqlite3_mem_m
12b00 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
12b10 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12b20 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ds {.  void *(*x
12b30 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20  Malloc)(int);   
12b40 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20        /* Memory 
12b50 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
12b60 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ion */.  void (*
12b70 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20  xFree)(void*);  
12b80 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20          /* Free 
12b90 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  a prior allocati
12ba0 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  on */.  void *(*
12bb0 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c  xRealloc)(void*,
12bc0 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65  int);  /* Resize
12bd0 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
12be0 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29  /.  int (*xSize)
12bf0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
12c00 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65     /* Return the
12c10 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f   size of an allo
12c20 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
12c30 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29  (*xRoundup)(int)
12c40 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f  ;          /* Ro
12c50 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73  und up request s
12c60 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f  ize to allocatio
12c70 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20  n size */.  int 
12c80 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b  (*xInit)(void*);
12c90 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e             /* In
12ca0 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
12cb0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
12cc0 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64  .  void (*xShutd
12cd0 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  own)(void*);    
12ce0 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a    /* Deinitializ
12cf0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
12d00 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
12d10 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
12d20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72             /* Ar
12d30 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28  gument to xInit(
12d40 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28  ) and xShutdown(
12d50 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ) */.};../*.** C
12d60 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
12d70 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
12d80 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e  * KEYWORDS: {con
12d90 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12da0 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  n}.**.** These c
12db0 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
12dc0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
12dd0 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
12de0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
12df0 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
12e00 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
12e10 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
12e20 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
12e30 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
12e40 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
12e50 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
12e60 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
12e70 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
12e80 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
12e90 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12ea0 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
12eb0 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
12ec0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
12ed0 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
12ee0 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
12ef0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12f00 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
12f10 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
12f20 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
12f30 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12f40 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
12f50 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
12f60 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
12f70 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
12f80 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
12f90 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
12fa0 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
12fb0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
12fc0 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  l>.** [[SQLITE_C
12fd0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
12fe0 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
12ff0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
13000 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
13010 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
13020 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
13030 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
13040 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
13050 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
13060 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
13070 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
13080 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
13090 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
130a0 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
130b0 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
130c0 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
130d0 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
130e0 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20  ingle thread.   
130f0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
13100 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
13110 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
13120 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
13130 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
13140 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
13150 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
13160 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
13170 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61  hange the [threa
13180 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20  ding mode] from 
13190 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76  its default.** v
131a0 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74  alue of Single-t
131b0 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71  hread and so [sq
131c0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
131d0 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20  will return .** 
131e0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
131f0 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
13200 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13210 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20  SINGLETHREAD.** 
13220 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13230 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
13240 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13250 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c  _MULTITHREAD]] <
13260 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13270 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74  _MULTITHREAD</dt
13280 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
13290 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
132a0 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
132b0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
132c0 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
132d0 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75  ding mode] to Mu
132e0 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  lti-thread.  In 
132f0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
13300 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
13310 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
13320 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
13330 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
13340 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
13350 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
13360 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
13370 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
13380 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
13390 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
133a0 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
133b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
133c0 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
133d0 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
133e0 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
133f0 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
13400 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
13410 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
13420 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
13430 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
13440 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
13450 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
13460 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13470 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
13480 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74  time.  ^If SQLit
13490 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
134a0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
134b0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
134c0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
134d0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
134e0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
134f0 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
13500 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75  le to set the Mu
13510 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
13520 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
13530 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
13540 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
13550 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
13560 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
13570 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
13580 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
13590 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
135a0 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
135b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
135c0 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c  G_SERIALIZED]] <
135d0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
135e0 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e  _SERIALIZED</dt>
135f0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
13600 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
13610 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
13620 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
13630 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
13640 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
13650 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65  ialized. In othe
13660 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70  r words, this op
13670 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
13680 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
13690 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
136a0 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
136b0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
136c0 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
136d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
136e0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
136f0 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
13700 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
13710 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
13720 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
13730 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
13740 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
13750 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
13760 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
13770 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
13780 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13790 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
137a0 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
137b0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
137c0 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
137d0 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
137e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
137f0 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
13800 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
13810 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
13820 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
13830 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
13840 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
13850 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13860 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
13870 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
13880 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
13890 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
138a0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
138b0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
138c0 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69   to set the Seri
138d0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
138e0 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
138f0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13900 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
13910 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
13920 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
13930 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
13940 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66  _SERIALIZED conf
13950 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13960 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
13970 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
13980 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
13990 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f  _CONFIG_MALLOC</
139a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
139b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
139c0 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61  MALLOC option ta
139d0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
139e0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a  ument which is .
139f0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
13a00 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
13a10 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
13a20 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13a30 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  re..** The argum
13a40 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
13a50 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
13a60 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
13a70 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
13a80 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
13a90 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
13aa0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13ab0 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
13ac0 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
13ad0 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a  ^SQLite makes.**
13ae0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
13af0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
13b00 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
13b10 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
13b20 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62  ] structure.** b
13b30 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74  efore the [sqlit
13b40 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c  e3_config()] cal
13b50 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a  l returns.</dd>.
13b60 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13b70 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
13b80 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13b90 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64  FIG_GETMALLOC</d
13ba0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
13bb0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
13bc0 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20  ETMALLOC option 
13bd0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
13be0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
13bf0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
13c00 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
13c10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
13c20 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
13c30 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ure..** The [sql
13c40 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
13c50 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
13c60 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
13c70 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
13c80 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
13c90 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29  ation routines.)
13ca0 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
13cb0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
13cc0 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
13cd0 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
13ce0 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
13cf0 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
13d00 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
13d10 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
13d20 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
13d30 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
13d40 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
13d50 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ple. </dd>.**.**
13d60 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13d70 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74  _MEMSTATUS]] <dt
13d80 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
13d90 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a  EMSTATUS</dt>.**
13da0 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
13db0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
13dc0 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  US option takes 
13dd0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
13de0 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20  of type int,.** 
13df0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
13e00 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
13e10 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
13e20 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
13e30 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20  on of.** memory 
13e40 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
13e50 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
13e60 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13e70 73 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a  statistics are.*
13e80 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20  * disabled, the 
13e90 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
13ea0 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
13eb0 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
13ec0 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
13ed0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
13ee0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
13ef0 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
13f00 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
13f10 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
13f20 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
13f30 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
13f40 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
13f50 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a  3_status64()].**
13f60 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d     </ul>)^.** ^M
13f70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13f80 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
13f90 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
13fa0 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65  lt unless SQLite
13fb0 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
13fc0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46  with [SQLITE_DEF
13fd0 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d  AULT_MEMSTATUS]=
13fe0 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
13ff0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
14000 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
14010 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
14020 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64  default..** </dd
14030 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14040 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
14050 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14060 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
14070 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
14080 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
14090 54 43 48 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  TCH option speci
140a0 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
140b0 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74  mory buffer.** t
140c0 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
140d0 73 65 20 66 6f 72 20 73 63 72 61 74 63 68 20 6d  se for scratch m
140e0 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72 65 20  emory.  ^(There 
140f0 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
14100 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45  nts.** to SQLITE
14110 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3a  _CONFIG_SCRATCH:
14120 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38    A pointer an 8
14130 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64  -byte.** aligned
14140 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66   memory buffer f
14150 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63  rom which the sc
14160 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
14170 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61  s will be.** dra
14180 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  wn, the size of 
14190 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c  each scratch all
141a0 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a  ocation (sz),.**
141b0 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d   and the maximum
141c0 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74   number of scrat
141d0 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28  ch allocations (
141e0 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72  N).)^.** The fir
141f0 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
14200 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
14210 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   an 8-byte align
14220 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20  ed buffer.** of 
14230 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
14240 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
14250 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
14260 6f 74 20 75 73 65 20 6d 6f 72 65 20 74 68 61 6e  ot use more than
14270 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66   one scratch buf
14280 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e  fers per thread.
14290 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
142a0 20 6e 65 76 65 72 20 72 65 71 75 65 73 74 20 61   never request a
142b0 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
142c0 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61  that is more tha
142d0 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65  n 6.** times the
142e0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73   database page s
142f0 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ize..** ^If SQLi
14300 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61  te needs needs a
14310 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72  dditional.** scr
14320 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f  atch memory beyo
14330 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
14340 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66  ded by this conf
14350 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14360 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69  , then .** [sqli
14370 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69  te3_malloc()] wi
14380 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  ll be used to ob
14390 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  tain the memory 
143a0 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57  needed.<p>.** ^W
143b0 68 65 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74  hen the applicat
143c0 69 6f 6e 20 70 72 6f 76 69 64 65 73 20 61 6e 79  ion provides any
143d0 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72 61 74   amount of scrat
143e0 63 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a  ch memory using.
143f0 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
14400 5f 53 43 52 41 54 43 48 2c 20 53 51 4c 69 74 65  _SCRATCH, SQLite
14410 20 61 76 6f 69 64 73 20 75 6e 6e 65 63 65 73 73   avoids unnecess
14420 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71  ary large.** [sq
14430 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61  lite3_malloc|hea
14440 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a  p allocations]..
14450 2a 2a 20 54 68 69 73 20 63 61 6e 20 68 65 6c 70  ** This can help
14460 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70   [Robson proof|p
14470 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c  revent memory al
14480 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
14490 73 5d 20 64 75 65 20 74 6f 20 68 65 61 70 0a 2a  s] due to heap.*
144a0 2a 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20  * fragmentation 
144b0 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d  in low-memory em
144c0 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 0a  bedded systems..
144d0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
144e0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
144f0 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53  AGECACHE]] <dt>S
14500 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
14510 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
14520 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
14530 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
14540 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
14550 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a  s a memory pool.
14560 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  ** that SQLite c
14570 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20 64  an use for the d
14580 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63  atabase page cac
14590 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61  he with the defa
145a0 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ult page.** cach
145b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
145c0 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
145d0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
145e0 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61   is a no-op if a
145f0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
14600 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63  fine page.** cac
14610 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
14620 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e  n is loaded usin
14630 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
14640 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a  NFIG_PCACHE2]..*
14650 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72  * ^There are thr
14660 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
14670 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
14680 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69 6e 74  GECACHE: A point
14690 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20  er to.** 8-byte 
146a0 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28  aligned memory (
146b0 70 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a 65 20  pMem), the size 
146c0 6f 66 20 65 61 63 68 20 70 61 67 65 20 63 61 63  of each page cac
146d0 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a  he line (sz),.**
146e0 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
146f0 6f 66 20 63 61 63 68 65 20 6c 69 6e 65 73 20 28  of cache lines (
14700 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
14710 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
14720 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
14730 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73   largest databas
14740 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77  e page.** (a pow
14750 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
14760 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33 36 29  n 512 and 65536)
14770 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61   plus some extra
14780 20 62 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a   bytes for each.
14790 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20  ** page header. 
147a0 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
147b0 65 78 74 72 61 20 62 79 74 65 73 20 6e 65 65 64  extra bytes need
147c0 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 68  ed by the page h
147d0 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20  eader.** can be 
147e0 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
147f0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
14800 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a  PCACHE_HDRSZ]..*
14810 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73  * ^It is harmles
14820 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68  s, apart from th
14830 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c  e wasted memory,
14840 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70  .** for the sz p
14850 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c  arameter to be l
14860 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73  arger than neces
14870 73 61 72 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a  sary.  The pMem.
14880 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
14890 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c   be either a NUL
148a0 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 20 70  L pointer or a p
148b0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
148c0 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62  yte.** aligned b
148d0 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f  lock of memory o
148e0 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
148f0 62 79 74 65 73 2c 20 6f 74 68 65 72 77 69 73 65  bytes, otherwise
14900 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 62  .** subsequent b
14910 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
14920 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70  ined..** ^When p
14930 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  Mem is not NULL,
14940 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 73 74 72   SQLite will str
14950 69 76 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d  ive to use the m
14960 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 0a 2a  emory provided.*
14970 2a 20 74 6f 20 73 61 74 69 73 66 79 20 70 61 67  * to satisfy pag
14980 65 20 63 61 63 68 65 20 6e 65 65 64 73 2c 20 66  e cache needs, f
14990 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b  alling back to [
149a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
149b0 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67 65 20 63  ] if.** a page c
149c0 61 63 68 65 20 6c 69 6e 65 20 69 73 20 6c 61 72  ache line is lar
149d0 67 65 72 20 74 68 61 6e 20 73 7a 20 62 79 74 65  ger than sz byte
149e0 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66 20 74  s or if all of t
149f0 68 65 20 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a  he pMem buffer.*
14a00 2a 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a  * is exhausted..
14a10 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e  ** ^If pMem is N
14a20 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e  ULL and N is non
14a30 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61 63 68  -zero, then each
14a40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
14a50 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20  tion.** does an 
14a60 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c  initial bulk all
14a70 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70 61 67 65  ocation for page
14a80 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a   cache memory.**
14a90 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
14aa0 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69 63 69  alloc()] suffici
14ab0 65 6e 74 20 66 6f 72 20 4e 20 63 61 63 68 65 20  ent for N cache 
14ac0 6c 69 6e 65 73 20 69 66 20 4e 20 69 73 20 70 6f  lines if N is po
14ad0 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20  sitive or.** of 
14ae0 2d 31 30 32 34 2a 4e 20 62 79 74 65 73 20 69 66  -1024*N bytes if
14af0 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20   N is negative, 
14b00 2e 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c  . ^If additional
14b10 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d  .** page cache m
14b20 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20  emory is needed 
14b30 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
14b40 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 69  rovided by the i
14b50 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61  nitial.** alloca
14b60 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74  tion, then SQLit
14b70 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
14b80 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70  e3_malloc()] sep
14b90 61 72 61 74 65 6c 79 20 66 6f 72 20 65 61 63 68  arately for each
14ba0 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  .** additional c
14bb0 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e  ache line. </dd>
14bc0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14bd0 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64  CONFIG_HEAP]] <d
14be0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14bf0 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  HEAP</dt>.** <dd
14c00 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
14c10 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
14c20 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
14c30 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
14c40 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  r .** that SQLit
14c50 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61  e will use for a
14c60 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
14c70 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
14c80 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79  ion needs.** bey
14c90 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64  ond those provid
14ca0 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54  ed for by [SQLIT
14cb0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
14cc0 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  ] and.** [SQLITE
14cd0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
14ce0 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49  E]..** ^The SQLI
14cf0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f  TE_CONFIG_HEAP o
14d00 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
14d10 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74  ailable if SQLit
14d20 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  e is compiled.**
14d30 20 77 69 74 68 20 65 69 74 68 65 72 20 5b 53 51   with either [SQ
14d40 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
14d50 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  YS3] or [SQLITE_
14d60 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
14d70 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  and returns.** [
14d80 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
14d90 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69   invoked otherwi
14da0 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72  se..** ^There ar
14db0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
14dc0 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  s to SQLITE_CONF
14dd0 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38  IG_HEAP:.** An 8
14de0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f  -byte aligned po
14df0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
14e00 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  ory,.** the numb
14e10 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
14e20 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
14e30 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
14e40 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
14e50 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  e..** ^If the fi
14e60 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
14e70 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
14e80 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
14e90 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
14ea0 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
14eb0 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
14ec0 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
14ed0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
14ee0 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
14ef0 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
14f00 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
14f10 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
14f20 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65  ALLOC].  ^If the
14f30 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
14f40 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  er is not NULL t
14f50 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
14f60 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
14f70 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
14f80 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
14f90 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
14fa0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
14fb0 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
14fc0 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
14fd0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
14fe0 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
14ff0 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
15000 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
15010 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
15020 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
15030 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
15040 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
15050 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
15060 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52  pped at 2**12. R
15070 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73  easonable values
15080 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69  .** for the mini
15090 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
150a0 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72  ize are 2**5 thr
150b0 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a  ough 2**8.</dd>.
150c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
150d0 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64  ONFIG_MUTEX]] <d
150e0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
150f0 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
15100 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
15110 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74  CONFIG_MUTEX opt
15120 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
15130 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
15140 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  h is a.** pointe
15150 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
15160 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
15170 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
15180 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
15190 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
151a0 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65  fies alternative
151b0 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
151c0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
151d0 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65  used.** in place
151e0 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
151f0 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
15200 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
15210 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
15220 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
15230 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
15240 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
15250 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
15260 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
15270 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
15280 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
15290 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
152a0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
152b0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
152c0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
152d0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
152e0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
152f0 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
15300 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
15310 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
15320 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
15330 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
15340 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
15350 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
15360 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
15370 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
15380 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
15390 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
153a0 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
153b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
153c0 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74  G_GETMUTEX]] <dt
153d0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
153e0 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
153f0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
15400 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
15410 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  X option takes a
15420 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
15430 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
15440 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
15450 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
15460 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
15470 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
15480 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
15490 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a  _mutex_methods].
154a0 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
154b0 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
154c0 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
154d0 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  d mutex routines
154e0 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
154f0 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
15500 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
15510 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c  efault mutex all
15520 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
15530 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
15540 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b  er used to track
15550 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72   mutex usage for
15560 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20   performance.** 
15570 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73  profiling or tes
15580 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c  ting, for exampl
15590 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  e.   ^If SQLite 
155a0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
155b0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
155c0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
155d0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
155e0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
155f0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
15600 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
15610 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
15620 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
15630 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
15640 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
15650 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
15660 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
15670 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63  ONFIG_GETMUTEX c
15680 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15690 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
156a0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
156b0 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
156c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
156d0 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51  OKASIDE]] <dt>SQ
156e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
156f0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
15700 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
15710 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
15720 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
15730 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
15740 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68   determine.** th
15750 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f  e default size o
15760 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  f lookaside memo
15770 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61  ry on each [data
15780 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
15790 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
157a0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
157b0 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
157c0 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
157d0 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
157e0 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
157f0 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
15800 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
15810 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15820 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45  ion.)^  ^(SQLITE
15830 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
15840 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69  E.** sets the <i
15850 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
15860 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
15870 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
15880 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
15890 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74  option to [sqlit
158a0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
158b0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
158c0 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
158d0 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
158e0 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
158f0 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
15900 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
15910 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15920 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
15930 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15940 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
15950 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
15960 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f  IG_PCACHE2 optio
15970 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
15980 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
15990 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  is .** a pointer
159a0 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
159b0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
159c0 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
159d0 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 0a  bject specifies.
159e0 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ** the interface
159f0 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67   to a custom pag
15a00 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
15a10 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51  tation.)^.** ^SQ
15a20 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
15a30 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
15a40 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
15a50 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a  2] object.</dd>.
15a60 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15a70 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
15a80 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
15a90 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c  NFIG_GETPCACHE2<
15aa0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
15ab0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15ac0 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70 74 69  _GETPCACHE2 opti
15ad0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
15ae0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
15af0 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
15b00 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
15b10 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
15b20 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65   object.  SQLite
15b30 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68   copies of.** th
15b40 65 20 63 75 72 72 65 6e 74 20 70 61 67 65 20 63  e current page c
15b50 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
15b60 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62  ion into that ob
15b70 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ject.)^ </dd>.**
15b80 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15b90 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51  FIG_LOG]] <dt>SQ
15ba0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
15bb0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  /dt>.** <dd> The
15bc0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
15bd0 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  OG option is use
15be0 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74  d to configure t
15bf0 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f  he SQLite.** glo
15c00 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e  bal [error log].
15c10 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45  .** (^The SQLITE
15c20 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
15c30 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
15c40 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65  uments: a pointe
15c50 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69  r to a.** functi
15c60 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73  on with a call s
15c70 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64  ignature of void
15c80 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  (*)(void*,int,co
15c90 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20  nst char*), .** 
15ca0 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  and a pointer to
15cb0 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66   void. ^If the f
15cc0 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
15cd0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20  is not NULL, it 
15ce0 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79  is.** invoked by
15cf0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
15d00 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68   to process each
15d10 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20   logging event. 
15d20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63   ^If the.** func
15d30 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
15d40 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74  NULL, the [sqlit
15d50 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66  e3_log()] interf
15d60 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f  ace becomes a no
15d70 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69  -op..** ^The voi
15d80 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  d pointer that i
15d90 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
15da0 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f  ument to SQLITE_
15db0 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a  CONFIG_LOG is.**
15dc0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
15dd0 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
15de0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70  ameter to the ap
15df0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
15e00 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
15e10 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68  tion whenever th
15e20 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  at function is i
15e30 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65  nvoked.  ^The se
15e40 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
15e50 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20  o.** the logger 
15e60 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f  function is a co
15e70 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  py of the first 
15e80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
15e90 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
15ea0 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  * [sqlite3_log()
15eb0 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e  ] call and is in
15ec0 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b  tended to be a [
15ed0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
15ee0 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  an.** [extended 
15ef0 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e  result code].  ^
15f00 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
15f10 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
15f20 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c  e logger is.** l
15f30 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72  og message after
15f40 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20   formatting via 
15f50 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
15f60 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  f()]..** The SQL
15f70 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65  ite logging inte
15f80 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65  rface is not ree
15f90 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67  ntrant; the logg
15fa0 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  er function.** s
15fb0 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61  upplied by the a
15fc0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
15fd0 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53  not invoke any S
15fe0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
15ff0 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74  .** In a multi-t
16000 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
16010 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61  ion, the applica
16020 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
16030 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
16040 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
16050 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  fe. </dd>.**.** 
16060 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16070 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  URI]] <dt>SQLITE
16080 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c  _CONFIG_URI.** <
16090 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  dd>^(The SQLITE_
160a0 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f  CONFIG_URI optio
160b0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
160c0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
160d0 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e  e int..** If non
160e0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20  -zero, then URI 
160f0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
16100 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66  ally enabled. If
16110 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
16120 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20  s zero,.** then 
16130 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
16140 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
16150 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e  d.)^ ^If URI han
16160 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
16170 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c  y.** enabled, al
16180 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73  l filenames pass
16190 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ed to [sqlite3_o
161a0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
161b0 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20  _open_v2()],.** 
161c0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
161d0 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69  )] or.** specifi
161e0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41  ed as part of [A
161f0 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20  TTACH] commands 
16200 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
16210 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c  as URIs, regardl
16220 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65  ess.** of whethe
16230 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
16240 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
16250 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
16260 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
16270 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
16280 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20  ened. ^If it is 
16290 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
162a0 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  d, filenames are
162b0 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72  .** only interpr
162c0 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20  eted as URIs if 
162d0 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
162e0 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20  URI flag is set 
162f0 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61  when the.** data
16300 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
16310 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20  is opened. ^(By 
16320 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e  default, URI han
16330 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
16340 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54  y.** disabled. T
16350 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
16360 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20   may be changed 
16370 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74  by compiling wit
16380 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
16390 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c  _USE_URI] symbol
163a0 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a   defined.)^.**.*
163b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
163c0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
163d0 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49  _SCAN]] <dt>SQLI
163e0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
163f0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a  NG_INDEX_SCAN.**
16400 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
16410 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
16420 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69  _INDEX_SCAN opti
16430 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
16440 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67  e integer.** arg
16450 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69  ument which is i
16460 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
16470 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72  boolean in order
16480 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
16490 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65  sable.** the use
164a0 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
164b0 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61  ices for full ta
164c0 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65  ble scans in the
164d0 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72   query optimizer
164e0 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
164f0 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74  t setting is det
16500 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68  ermined.** by th
16510 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f  e [SQLITE_ALLOW_
16520 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
16530 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  CAN] compile-tim
16540 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20  e option, or is 
16550 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20  "on".** if that 
16560 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
16570 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ion is omitted..
16580 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74  ** The ability t
16590 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73  o disable the us
165a0 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e  e of covering in
165b0 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74  dices for full t
165c0 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73  able scans.** is
165d0 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e   because some in
165e0 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20  correctly coded 
165f0 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69  legacy applicati
16600 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e  ons might malfun
16610 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68  ction.** when th
16620 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69  e optimization i
16630 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76  s enabled.  Prov
16640 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74  iding the abilit
16650 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20  y to.** disable 
16660 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
16670 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65   allows the olde
16680 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61  r, buggy applica
16690 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72  tion code to wor
166a0 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61  k.** without cha
166b0 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65  nge even with ne
166c0 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
166d0 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  SQLite..**.** [[
166e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
166f0 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f  ACHE]] [[SQLITE_
16700 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
16710 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
16720 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61  _CONFIG_PCACHE a
16730 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  nd SQLITE_CONFIG
16740 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64  _GETPCACHE.** <d
16750 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73  d> These options
16760 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e   are obsolete an
16770 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  d should not be 
16780 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65  used by new code
16790 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65  ..** They are re
167a0 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77  tained for backw
167b0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
167c0 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e  ty but are now n
167d0 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  o-ops..** </dd>.
167e0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
167f0 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a  ONFIG_SQLLOG]].*
16800 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
16810 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64  FIG_SQLLOG.** <d
16820 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  d>This option is
16830 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
16840 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d  if sqlite is com
16850 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
16860 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
16870 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f  _SQLLOG] pre-pro
16880 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66  cessor macro def
16890 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20  ined. The first 
168a0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a  argument should.
168b0 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ** be a pointer 
168c0 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
168d0 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f   type void(*)(vo
168e0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e  id*,sqlite3*,con
168f0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a  st char*, int)..
16900 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68  ** The second sh
16910 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20  ould be of type 
16920 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c  (void*). The cal
16930 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
16940 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a   by the library.
16950 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61  ** in three sepa
16960 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63  rate circumstanc
16970 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62  es, identified b
16980 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73  y the value pass
16990 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  ed as the.** fou
169a0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49  rth parameter. I
169b0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
169c0 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65  ameter is 0, the
169d0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
169e0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73  onnection.** pas
169f0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
16a00 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a  d argument has j
16a10 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e  ust been opened.
16a20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
16a30 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ent.** points to
16a40 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69   a buffer contai
16a50 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66  ning the name of
16a60 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
16a70 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a  se file. If the.
16a80 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
16a90 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74  ter is 1, then t
16aa0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
16ab0 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20   that the third 
16ac0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69  parameter.** poi
16ad0 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20  nts to has just 
16ae0 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f  been executed. O
16af0 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68  r, if the fourth
16b00 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c   parameter is 2,
16b10 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e   then.** the con
16b20 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61  nection being pa
16b30 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
16b40 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
16b50 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68  being closed. Th
16b60 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
16b70 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e  eter is passed N
16b80 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65  ULL In this case
16b90 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66  .  An example of
16ba0 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63   using this.** c
16bb0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
16bc0 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20  ion can be seen 
16bd0 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c  in the "test_sql
16be0 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69  log.c" source fi
16bf0 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e  le in.** the can
16c00 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f  onical SQLite so
16c10 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a  urce tree.</dd>.
16c20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16c30 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d  ONFIG_MMAP_SIZE]
16c40 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
16c50 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
16c60 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f  .** <dd>^SQLITE_
16c70 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
16c80 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69   takes two 64-bi
16c90 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74  t integer (sqlit
16ca0 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73  e3_int64) values
16cb0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65  .** that are the
16cc0 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69   default mmap si
16cd0 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65  ze limit (the de
16ce0 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f  fault setting fo
16cf0 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61  r.** [PRAGMA mma
16d00 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65  p_size]) and the
16d10 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
16d20 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
16d30 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
16d40 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65  t setting can be
16d50 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65   overridden by e
16d60 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
16d70 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  nection using.**
16d80 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41   either the [PRA
16d90 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63  GMA mmap_size] c
16da0 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73  ommand, or by us
16db0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
16dc0 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
16dd0 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
16de0 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d  .  ^(The maximum
16df0 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
16e00 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69  ze.** will be si
16e10 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
16e20 20 69 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f   if necessary so
16e30 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f   that it does no
16e40 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20  t exceed the.** 
16e50 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78  compile-time max
16e60 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73  imum mmap size s
16e70 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
16e80 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49  LITE_MAX_MMAP_SI
16e90 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ZE] compile-time
16ea0 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49   option.)^.** ^I
16eb0 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e  f either argumen
16ec0 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  t to this option
16ed0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
16ee0 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74  en that argument
16ef0 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74   is.** changed t
16f00 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69  o its compile-ti
16f10 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  me default..**.*
16f20 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
16f30 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
16f40 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
16f50 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
16f60 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54  APSIZE.** <dd>^T
16f70 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
16f80 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
16f90 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
16fa0 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69  vailable if SQLi
16fb0 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
16fc0 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69  d for Windows wi
16fd0 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57  th the [SQLITE_W
16fe0 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65  IN32_MALLOC] pre
16ff0 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
17000 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51  .** defined. ^SQ
17010 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
17020 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73  2_HEAPSIZE takes
17030 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e   a 32-bit unsign
17040 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  ed integer value
17050 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66 69  .** that specifi
17060 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73  es the maximum s
17070 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61 74  ize of the creat
17080 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b  ed heap..**.** [
17090 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
170a0 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a  CACHE_HDRSZ]].**
170b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
170c0 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a  IG_PCACHE_HDRSZ.
170d0 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
170e0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
170f0 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61  _HDRSZ option ta
17100 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72  kes a single par
17110 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ameter which.** 
17120 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
17130 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77  an integer and w
17140 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20  rites into that 
17150 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62  integer the numb
17160 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62  er of extra.** b
17170 79 74 65 73 20 70 65 72 20 70 61 67 65 20 72 65  ytes per page re
17180 71 75 69 72 65 64 20 66 6f 72 20 65 61 63 68 20  quired for each 
17190 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f  page in [SQLITE_
171a0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
171b0 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74  ]..** The amount
171c0 20 6f 66 20 65 78 74 72 61 20 73 70 61 63 65 20   of extra space 
171d0 72 65 71 75 69 72 65 64 20 63 61 6e 20 63 68 61  required can cha
171e0 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  nge depending on
171f0 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a   the compiler,.*
17200 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72  * target platfor
17210 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65  m, and SQLite ve
17220 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  rsion..**.** [[S
17230 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
17240 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  SZ]].** <dt>SQLI
17250 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a  TE_CONFIG_PMASZ.
17260 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
17270 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20  TE_CONFIG_PMASZ 
17280 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
17290 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20  ingle parameter 
172a0 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75  which.** is an u
172b0 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
172c0 61 6e 64 20 73 65 74 73 20 74 68 65 20 22 4d 69  and sets the "Mi
172d0 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20  nimum PMA Size" 
172e0 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72  for the multithr
172f0 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20  eaded.** sorter 
17300 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  to that integer.
17310 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69    The default mi
17320 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69  nimum PMA Size i
17330 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20  s set by the.** 
17340 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50  [SQLITE_SORTER_P
17350 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  MASZ] compile-ti
17360 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20  me option.  New 
17370 74 68 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e  threads are laun
17380 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20  ched.** to help 
17390 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74  with sort operat
173a0 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74  ions when multit
173b0 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a  hreaded sorting.
173c0 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75  ** is enabled (u
173d0 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  sing the [PRAGMA
173e0 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e   threads] comman
173f0 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e  d) and the amoun
17400 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20  t of content.** 
17410 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65 78 63  to be sorted exc
17420 65 65 64 73 20 74 68 65 20 70 61 67 65 20 73 69  eeds the page si
17430 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e  ze times the min
17440 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  imum of the.** [
17450 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a  PRAGMA cache_siz
17460 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74  e] setting and t
17470 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  his value..**.**
17480 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
17490 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d  _STMTJRNL_SPILL]
174a0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
174b0 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f  CONFIG_STMTJRNL_
174c0 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68  SPILL.** <dd>^Th
174d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
174e0 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f  STMTJRNL_SPILL o
174f0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
17500 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77  ngle parameter w
17510 68 69 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20  hich.** becomes 
17520 74 68 65 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a  the [statement j
17530 6f 75 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f  ournal] spill-to
17540 2d 64 69 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e  -disk threshold.
17550 20 20 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74    .** [Statement
17560 20 6a 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20 68   journals] are h
17570 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e  eld in memory un
17580 74 69 6c 20 74 68 65 69 72 20 73 69 7a 65 20 28  til their size (
17590 69 6e 20 62 79 74 65 73 29 0a 2a 2a 20 65 78 63  in bytes).** exc
175a0 65 65 64 73 20 74 68 69 73 20 74 68 72 65 73 68  eeds this thresh
175b0 6f 6c 64 2c 20 61 74 20 77 68 69 63 68 20 70 6f  old, at which po
175c0 69 6e 74 20 74 68 65 79 20 61 72 65 20 77 72 69  int they are wri
175d0 74 74 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a  tten to disk..**
175e0 20 4f 72 20 69 66 20 74 68 65 20 74 68 72 65 73   Or if the thres
175f0 68 6f 6c 64 20 69 73 20 2d 31 2c 20 73 74 61 74  hold is -1, stat
17600 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61  ement journals a
17610 72 65 20 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a  re always held.*
17620 2a 20 65 78 63 6c 75 73 69 76 65 6c 79 20 69 6e  * exclusively in
17630 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63   memory..** Sinc
17640 65 20 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e 74  e many statement
17650 20 6a 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72 20   journals never 
17660 62 65 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65  become large, se
17670 74 74 69 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a  tting the spill.
17680 2a 2a 20 74 68 72 65 73 68 6f 6c 64 20 74 6f 20  ** threshold to 
17690 61 20 76 61 6c 75 65 20 73 75 63 68 20 61 73 20  a value such as 
176a0 36 34 4b 69 42 20 63 61 6e 20 67 72 65 61 74 6c  64KiB can greatl
176b0 79 20 72 65 64 75 63 65 20 74 68 65 20 61 6d 6f  y reduce the amo
176c0 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65  unt of.** I/O re
176d0 71 75 69 72 65 64 20 74 6f 20 73 75 70 70 6f 72  quired to suppor
176e0 74 20 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c  t statement roll
176f0 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66  back..** The def
17700 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74  ault value for t
17710 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 20 63  his setting is c
17720 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 74 68 65  ontrolled by the
17730 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54  .** [SQLITE_STMT
17740 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70  JRNL_SPILL] comp
17750 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
17760 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
17770 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17780 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
17790 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   1  /* nil */.#d
177a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
177b0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
177c0 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    2  /* nil */.#
177d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
177e0 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
177f0 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     3  /* nil */.
17800 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17810 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20  ONFIG_MALLOC    
17820 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
17830 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
17840 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17850 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
17860 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69  C     5  /* sqli
17870 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
17880 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17890 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
178a0 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f  H       6  /* vo
178b0 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
178c0 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
178d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
178e0 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
178f0 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
17900 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
17910 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
17920 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
17930 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
17940 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
17950 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17960 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
17970 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
17980 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17990 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
179a0 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
179b0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
179c0 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
179d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
179e0 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
179f0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
17a00 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70  methods* */./* p
17a10 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45  reviously SQLITE
17a20 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
17a30 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e  OC 12 which is n
17a40 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23  ow unused. */ .#
17a50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17a60 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
17a70 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74    13  /* int int
17a80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17a90 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
17aa0 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f         14  /* no
17ab0 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
17ac0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
17ad0 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a  PCACHE    15  /*
17ae0 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
17af0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17b00 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20  LOG          16 
17b10 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a   /* xFunc, void*
17b20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17b30 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20  TE_CONFIG_URI   
17b40 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e         17  /* in
17b50 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
17b60 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
17b70 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73  E2      18  /* s
17b80 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
17b90 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
17ba0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17bb0 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39  _GETPCACHE2   19
17bc0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
17bd0 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
17be0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17bf0 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
17c00 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f  INDEX_SCAN 20  /
17c10 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
17c20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
17c30 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20  QLLOG       21  
17c40 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64  /* xSqllog, void
17c50 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
17c60 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
17c70 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73  SIZE    22  /* s
17c80 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71  qlite3_int64, sq
17c90 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23  lite3_int64 */.#
17ca0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17cb0 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
17cc0 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20  IZE      23  /* 
17cd0 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65  int nByte */.#de
17ce0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17cf0 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20  IG_PCACHE_HDRSZ 
17d00 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e         24  /* in
17d10 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e  t *psz */.#defin
17d20 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17d30 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20  PMASZ           
17d40 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67      25  /* unsig
17d50 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f  ned int szPma */
17d60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17d70 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f  CONFIG_STMTJRNL_
17d80 53 50 49 4c 4c 20 20 20 20 20 20 32 36 20 20 2f  SPILL      26  /
17d90 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a  * int nByte */..
17da0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17db0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
17dc0 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
17dd0 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
17de0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
17df0 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
17e00 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
17e10 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
17e20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
17e30 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
17e40 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
17e50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
17e60 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
17e70 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
17e80 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
17e90 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
17ea0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
17eb0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
17ec0 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
17ed0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
17ee0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
17ef0 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
17f00 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
17f10 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
17f20 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
17f30 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
17f40 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
17f50 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
17f60 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
17f70 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
17f80 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
17f90 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
17fa0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
17fb0 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
17fc0 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
17fd0 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
17fe0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
17ff0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
18000 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
18010 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
18020 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
18030 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
18040 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
18050 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
18060 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
18070 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
18080 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
18090 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
180a0 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
180b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
180c0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
180d0 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
180e0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
180f0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
18100 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
18110 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
18120 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
18130 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
18140 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
18150 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
18160 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
18170 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
18180 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
18190 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
181a0 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
181b0 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
181c0 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
181d0 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
181e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
181f0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
18200 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
18210 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
18220 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
18230 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
18240 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
18250 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
18260 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
18270 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
18280 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
18290 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
182a0 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
182b0 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
182c0 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
182d0 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
182e0 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
182f0 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
18300 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
18310 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
18320 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
18330 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
18340 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
18350 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
18360 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
18370 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
18380 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
18390 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
183a0 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  r multiple of 8.
183b0 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64    ^(The lookasid
183c0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66  e memory.** conf
183d0 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20  iguration for a 
183e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
183f0 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ion can only be 
18400 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61  changed when tha
18410 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  t.** connection 
18420 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
18430 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65   using lookaside
18440 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f   memory, or in o
18450 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68  ther words.** wh
18460 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20  en the "current 
18470 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20  value" returned 
18480 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64  by.** [sqlite3_d
18490 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c  b_status](D,[SQL
184a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
184b0 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65  SIDE],...) is ze
184c0 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ro..** Any attem
184d0 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  pt to change the
184e0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
184f0 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  y configuration 
18500 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a  when lookaside.*
18510 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75  * memory is in u
18520 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f  se leaves the co
18530 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68  nfiguration unch
18540 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
18550 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  s .** [SQLITE_BU
18560 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  SY].)^</dd>.**.*
18570 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
18580 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
18590 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  Y</dt>.** <dd> ^
185a0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
185b0 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
185c0 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66   disable the enf
185d0 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b  orcement of.** [
185e0 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
185f0 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65  traints].  There
18600 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
18610 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
18620 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
18630 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
18640 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
18650 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46  s 0 to disable F
18660 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a  K enforcement,.*
18670 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
18680 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
18690 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ent or negative 
186a0 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f  to leave FK enfo
186b0 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61  rcement.** uncha
186c0 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e  nged.  The secon
186d0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
186e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
186f0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
18700 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
18710 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
18720 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e  te whether FK en
18730 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66  forcement is off
18740 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77   or on.** follow
18750 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
18760 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
18770 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
18780 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
18790 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
187a0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
187b0 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
187c0 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
187d0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
187e0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
187f0 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74  ABLE_TRIGGER</dt
18800 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
18810 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
18820 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
18830 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47  ble [CREATE TRIG
18840 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e  GER | triggers].
18850 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
18860 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
18870 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
18880 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
18890 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
188a0 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
188b0 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73  disable triggers
188c0 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
188d0 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73   enable triggers
188e0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
188f0 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
18900 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
18910 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
18920 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
18930 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
18940 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
18950 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
18960 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
18970 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65  her triggers are
18980 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
18990 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
189a0 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
189b0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
189c0 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
189d0 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
189e0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74  which case the t
189f0 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69  rigger setting i
18a00 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
18a10 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
18a20 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
18a30 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33  NFIG_ENABLE_FTS3
18a40 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a  _TOKENIZER</dt>.
18a50 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
18a60 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
18a70 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
18a80 65 20 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65  e the two-argume
18a90 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  nt.** version of
18aa0 20 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e   the [fts3_token
18ab0 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e  izer()] function
18ac0 20 77 68 69 63 68 20 69 73 20 70 61 72 74 20 6f   which is part o
18ad0 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20  f the.** [FTS3] 
18ae0 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68  full-text search
18af0 20 65 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f   engine extensio
18b00 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  n..** There shou
18b10 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
18b20 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
18b30 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
18b40 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
18b50 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
18b60 6f 20 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74  o disable fts3_t
18b70 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a  okenizer() or.**
18b80 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
18b90 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  ble fts3_tokeniz
18ba0 65 72 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65  er() or negative
18bb0 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
18bc0 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67  tting.** unchang
18bd0 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
18be0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
18bf0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
18c00 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
18c10 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
18c20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
18c30 74 65 20 77 68 65 74 68 65 72 20 66 74 73 33 5f  te whether fts3_
18c40 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73  tokenizer is dis
18c50 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
18c60 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
18c70 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
18c80 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
18c90 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
18ca0 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
18cb0 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73  h case the new s
18cc0 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
18cd0 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
18ce0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18cf0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
18d00 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49  BLE_LOAD_EXTENSI
18d10 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ON</dt>.** <dd> 
18d20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
18d30 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
18d40 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73  r disable the [s
18d50 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
18d60 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65  nsion()].** inte
18d70 72 66 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e  rface independen
18d80 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64  tly of the [load
18d90 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51  _extension()] SQ
18da0 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  L function..** T
18db0 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  he [sqlite3_enab
18dc0 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
18dd0 6e 28 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73  n()] API enables
18de0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74   or disables bot
18df0 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b  h the.** C-API [
18e00 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
18e10 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68  ension()] and th
18e20 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b  e SQL function [
18e30 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
18e40 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
18e50 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
18e60 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
18e70 2a 2a 20 57 68 65 6e 20 74 68 65 20 66 69 72 73  ** When the firs
18e80 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
18e90 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
18ea0 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65  1, then only the
18eb0 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61   C-API is.** ena
18ec0 62 6c 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  bled and the SQL
18ed0 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e   function remain
18ee0 73 20 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20  s disabled.  If 
18ef0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
18f00 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e  nt to.** this in
18f10 74 65 72 66 61 63 65 20 69 73 20 30 2c 20 74 68  terface is 0, th
18f20 65 6e 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50  en both the C-AP
18f30 49 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75  I and the SQL fu
18f40 6e 63 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62  nction are disab
18f50 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  led..** If the f
18f60 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
18f70 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61   -1, then no cha
18f80 6e 67 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f  nges are made to
18f90 20 73 74 61 74 65 20 6f 66 20 65 69 74 68 65 72   state of either
18fa0 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72   the.** C-API or
18fb0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
18fc0 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  n..** The second
18fd0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
18fe0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
18ff0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
19000 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
19010 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
19020 65 20 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74  e whether [sqlit
19030 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
19040 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  n()] interface.*
19050 2a 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72  * is disabled or
19060 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69   enabled followi
19070 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
19080 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
19090 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20  ter may.** be a 
190a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
190b0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
190c0 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e  new setting is n
190d0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
190e0 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
190f0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
19100 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c  NFIG_MAINDBNAME<
19110 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
19120 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
19130 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
19140 6e 61 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69  name of the "mai
19150 6e 22 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73  n" database.** s
19160 63 68 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c  chema.  ^The sol
19170 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
19180 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e  pointer to a con
19190 73 74 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e  stant UTF8 strin
191a0 67 0a 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20  g.** which will 
191b0 62 65 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73  become the new s
191c0 63 68 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c  chema name in pl
191d0 61 63 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20  ace of "main".  
191e0 5e 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20  ^SQLite.** does 
191f0 6e 6f 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  not make a copy 
19200 6f 66 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20  of the new main 
19210 73 63 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69  schema name stri
19220 6e 67 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69  ng, so the appli
19230 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65  cation.** must e
19240 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61  nsure that the a
19250 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
19260 6e 74 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49  nto this DBCONFI
19270 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68  G option is unch
19280 61 6e 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61  anged.** until a
19290 66 74 65 72 20 74 68 65 20 64 61 74 61 62 61 73  fter the databas
192a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
192b0 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ses..** </dd>.**
192c0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
192d0 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f  BCONFIG_NO_CKPT_
192e0 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a  ON_CLOSE</dt>.**
192f0 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77   <dd> Usually, w
19300 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 69  hen a database i
19310 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c  n wal mode is cl
19320 6f 73 65 64 20 6f 72 20 64 65 74 61 63 68 65 64  osed or detached
19330 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61   from a .** data
19340 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c  base handle, SQL
19350 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 68  ite checks if th
19360 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61  is will mean tha
19370 74 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20  t there are now 
19380 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  no .** connectio
19390 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65  ns at all to the
193a0 20 64 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f   database. If so
193b0 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20  , it performs a 
193c0 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f  checkpoint .** o
193d0 70 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20  peration before 
193e0 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e  closing the conn
193f0 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74  ection. This opt
19400 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20  ion may be used 
19410 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74  to.** override t
19420 68 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54  his behaviour. T
19430 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
19440 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69  er passed to thi
19450 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69  s operation.** i
19460 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 6e  s an integer - n
19470 6f 6e 2d 7a 65 72 6f 20 74 6f 20 64 69 73 61 62  on-zero to disab
19480 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f  le checkpoints-o
19490 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f  n-close, or zero
194a0 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74   (the.** default
194b0 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d  ) to enable them
194c0 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  . The second par
194d0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
194e0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
194f0 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20  r.** into which 
19500 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
19510 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
19520 65 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74  ether checkpoint
19530 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61  s-on-close.** ha
19540 76 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64  ve been disabled
19550 20 2d 20 30 20 69 66 20 74 68 65 79 20 61 72 65   - 0 if they are
19560 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31   not disabled, 1
19570 20 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a   if they are..**
19580 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
19590 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
195a0 5f 45 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74  _ENABLE_QPSG</dt
195b0 3e 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53  >.** <dd>^(The S
195c0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
195d0 4e 41 42 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f  NABLE_QPSG optio
195e0 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64  n activates or d
195f0 65 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68  eactivates.** th
19600 65 20 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  e [query planner
19610 20 73 74 61 62 69 6c 69 74 79 20 67 75 61 72 61   stability guara
19620 6e 74 65 65 5d 20 28 51 50 53 47 29 2e 20 20 57  ntee] (QPSG).  W
19630 68 65 6e 20 74 68 65 20 51 50 53 47 20 69 73 20  hen the QPSG is 
19640 61 63 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e  active,.** a sin
19650 67 6c 65 20 53 51 4c 20 71 75 65 72 79 20 73 74  gle SQL query st
19660 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77  atement will alw
19670 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d 65  ays use the same
19680 20 61 6c 67 6f 72 69 74 68 6d 20 72 65 67 61 72   algorithm regar
19690 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75  dless.** of valu
196a0 65 73 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72  es of [bound par
196b0 61 6d 65 74 65 72 73 5d 2e 29 5e 20 54 68 65 20  ameters].)^ The 
196c0 51 50 53 47 20 64 69 73 61 62 6c 65 73 20 73 6f  QPSG disables so
196d0 6d 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a  me query optimiz
196e0 61 74 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c  ations.** that l
196f0 6f 6f 6b 20 61 74 20 74 68 65 20 76 61 6c 75 65  ook at the value
19700 73 20 6f 66 20 62 6f 75 6e 64 20 70 61 72 61 6d  s of bound param
19710 65 74 65 72 73 2c 20 77 68 69 63 68 20 63 61 6e  eters, which can
19720 20 6d 61 6b 65 20 73 6f 6d 65 20 71 75 65 72 69   make some queri
19730 65 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42  es.** slower.  B
19740 75 74 20 74 68 65 20 51 50 53 47 20 68 61 73 20  ut the QPSG has 
19750 74 68 65 20 61 64 76 61 6e 74 61 67 65 20 6f 66  the advantage of
19760 20 6d 6f 72 65 20 70 72 65 64 69 63 74 61 62 6c   more predictabl
19770 65 20 62 65 68 61 76 69 6f 72 2e 20 20 57 69 74  e behavior.  Wit
19780 68 0a 2a 2a 20 74 68 65 20 51 50 53 47 20 61 63  h.** the QPSG ac
19790 74 69 76 65 2c 20 53 51 4c 69 74 65 20 77 69 6c  tive, SQLite wil
197a0 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 65  l always use the
197b0 20 73 61 6d 65 20 71 75 65 72 79 20 70 6c 61 6e   same query plan
197c0 20 69 6e 20 74 68 65 20 66 69 65 6c 64 20 61 73   in the field as
197d0 0a 2a 2a 20 77 61 73 20 75 73 65 64 20 64 75 72  .** was used dur
197e0 69 6e 67 20 74 65 73 74 69 6e 67 20 69 6e 20 74  ing testing in t
197f0 68 65 20 6c 61 62 2e 0a 2a 2a 20 3c 2f 64 64 3e  he lab..** </dd>
19800 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
19810 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19820 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41  BCONFIG_MAINDBNA
19830 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 31 30  ME            10
19840 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63 68 61 72  00 /* const char
19850 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
19860 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
19870 4b 41 53 49 44 45 20 20 20 20 20 20 20 20 20 20  KASIDE          
19880 20 20 20 31 30 30 31 20 2f 2a 20 76 6f 69 64 2a     1001 /* void*
19890 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
198a0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
198b0 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20  FIG_ENABLE_FKEY 
198c0 20 20 20 20 20 20 20 20 20 20 31 30 30 32 20 2f            1002 /
198d0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
198e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
198f0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
19900 47 47 45 52 20 20 20 20 20 20 20 20 31 30 30 33  GGER        1003
19910 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
19920 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19930 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
19940 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20 31 30  TS3_TOKENIZER 10
19950 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  04 /* int int* *
19960 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19970 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
19980 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20  _LOAD_EXTENSION 
19990 31 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1005 /* int int*
199a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
199b0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43  TE_DBCONFIG_NO_C
199c0 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20 20 20  KPT_ON_CLOSE    
199d0 20 20 31 30 30 36 20 2f 2a 20 69 6e 74 20 69 6e    1006 /* int in
199e0 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
199f0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
19a00 41 42 4c 45 5f 51 50 53 47 20 20 20 20 20 20 20  ABLE_QPSG       
19a10 20 20 20 20 31 30 30 37 20 2f 2a 20 69 6e 74 20      1007 /* int 
19a20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20  int* */.../*.** 
19a30 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
19a40 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
19a50 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
19a60 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
19a70 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
19a80 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
19a90 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20  _result_codes() 
19aa0 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
19ab0 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
19ac0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
19ad0 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
19ae0 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54  re of SQLite. ^T
19af0 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
19b00 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
19b10 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
19b20 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
19b30 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
19b40 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
19b50 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
19b60 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
19b70 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
19b80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
19b90 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a  st Insert Rowid.
19ba0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
19bb0 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65  e3.**.** ^Each e
19bc0 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c  ntry in most SQL
19bd0 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65  ite tables (exce
19be0 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20  pt for [WITHOUT 
19bf0 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a  ROWID] tables).*
19c00 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  * has a unique 6
19c10 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
19c20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
19c30 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
19c40 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
19c50 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
19c60 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
19c70 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
19c80 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
19c90 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
19ca0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
19cb0 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
19cc0 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
19cd0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
19ce0 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
19cf0 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
19d00 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
19d10 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
19d20 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
19d30 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
19d40 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
19d50 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
19d60 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
19d70 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19d80 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 75  d(D) interface u
19d90 73 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  sually returns t
19da0 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a 2a  he [rowid] of.**
19db0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
19dc0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
19dd0 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69  ERT] into a rowi
19de0 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74  d table or [virt
19df0 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e  ual table].** on
19e00 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
19e10 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72 74 73  tion D. ^Inserts
19e20 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52   into [WITHOUT R
19e30 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65  OWID] tables are
19e40 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64 65 64   not.** recorded
19e50 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  . ^If no success
19e60 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e  ful [INSERT]s in
19e70 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20  to rowid tables 
19e80 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
19e90 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20 64 61  ed .** on the da
19ea0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19eb0 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  n D, then sqlite
19ec0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
19ed0 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 0a  wid(D) returns .
19ee0 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 41  ** zero..**.** A
19ef0 73 20 77 65 6c 6c 20 61 73 20 62 65 69 6e 67 20  s well as being 
19f00 73 65 74 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  set automaticall
19f10 79 20 61 73 20 72 6f 77 73 20 61 72 65 20 69 6e  y as rows are in
19f20 73 65 72 74 65 64 20 69 6e 74 6f 20 64 61 74 61  serted into data
19f30 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73 2c 20  base.** tables, 
19f40 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
19f50 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
19f60 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 74 20 65  ion may be set e
19f70 78 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a 2a 20  xplicitly by.** 
19f80 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73  [sqlite3_set_las
19f90 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
19fa0 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69 72  ].**.** Some vir
19fb0 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
19fc0 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 49  mentations may I
19fd0 4e 53 45 52 54 20 72 6f 77 73 20 69 6e 74 6f 20  NSERT rows into 
19fe0 72 6f 77 69 64 20 74 61 62 6c 65 73 20 61 73 0a  rowid tables as.
19ff0 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d 6d 69  ** part of commi
1a000 74 74 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74  tting a transact
1a010 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66 6c 75  ion (e.g. to flu
1a020 73 68 20 64 61 74 61 20 61 63 63 75 6d 75 6c 61  sh data accumula
1a030 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a  ted in memory.**
1a040 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20 74 68   to disk). In th
1a050 69 73 20 63 61 73 65 20 73 75 62 73 65 71 75 65  is case subseque
1a060 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74 68 69 73  nt calls to this
1a070 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1a080 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 61 73   the rowid.** as
1a090 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
1a0a0 65 73 65 20 69 6e 74 65 72 6e 61 6c 20 49 4e 53  ese internal INS
1a0b0 45 52 54 20 6f 70 65 72 61 74 69 6f 6e 73 2c 20  ERT operations, 
1a0c0 77 68 69 63 68 20 6c 65 61 64 73 20 74 6f 20 0a  which leads to .
1a0d0 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76 65 20 72  ** unintuitive r
1a0e0 65 73 75 6c 74 73 2e 20 56 69 72 74 75 61 6c 20  esults. Virtual 
1a0f0 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
1a100 74 69 6f 6e 73 20 74 68 61 74 20 64 6f 20 77 72  tions that do wr
1a110 69 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a 2a 20  ite to rowid.** 
1a120 74 61 62 6c 65 73 20 69 6e 20 74 68 69 73 20 77  tables in this w
1a130 61 79 20 63 61 6e 20 61 76 6f 69 64 20 74 68 69  ay can avoid thi
1a140 73 20 70 72 6f 62 6c 65 6d 20 62 79 20 72 65 73  s problem by res
1a150 74 6f 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69  toring the origi
1a160 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20 76 61  nal .** rowid va
1a170 6c 75 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  lue using [sqlit
1a180 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65  e3_set_last_inse
1a190 72 74 5f 72 6f 77 69 64 28 29 5d 20 62 65 66 6f  rt_rowid()] befo
1a1a0 72 65 20 72 65 74 75 72 6e 69 6e 67 20 0a 2a 2a  re returning .**
1a1b0 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68 65 20   control to the 
1a1c0 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  user..**.** ^(If
1a1d0 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63   an [INSERT] occ
1a1e0 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
1a1f0 67 67 65 72 20 74 68 65 6e 20 74 68 69 73 20 72  gger then this r
1a200 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a 20  outine will .** 
1a210 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69  return the [rowi
1a220 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  d] of the insert
1a230 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61  ed row as long a
1a240 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73  s the trigger is
1a250 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f 6e   .** running. On
1a260 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 70  ce the trigger p
1a270 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74 68 65  rogram ends, the
1a280 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1a290 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74  .** by this rout
1a2a0 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77  ine reverts to w
1a2b0 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72  hat it was befor
1a2c0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 77 61  e the trigger wa
1a2d0 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  s fired.)^.**.**
1a2e0 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68   ^An [INSERT] th
1a2f0 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20  at fails due to 
1a300 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
1a310 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a  lation is not a.
1a320 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
1a330 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20  NSERT] and does 
1a340 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
1a350 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1a360 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
1a370 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20  .  ^Thus INSERT 
1a380 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
1a390 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
1a3a0 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
1a3b0 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
1a3c0 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
1a3d0 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
1a3e0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
1a3f0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
1a400 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
1a410 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e  n fails.  ^(When
1a420 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
1a430 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73  CE.** encounters
1a440 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
1a450 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73  olation, it does
1a460 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a   not fail.  The.
1a470 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e  ** INSERT contin
1a480 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
1a490 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67  n after deleting
1a4a0 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65   rows that cause
1a4b0 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61  d.** the constra
1a4c0 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49  int problem so I
1a4d0 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
1a4e0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61   will always cha
1a4f0 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  nge.** the retur
1a500 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
1a510 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a  interface.)^.**.
1a520 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
1a530 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
1a540 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54  tine, an [INSERT
1a550 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  ] is considered 
1a560 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73  to.** be success
1a570 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69  ful even if it i
1a580 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72  s subsequently r
1a590 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
1a5a0 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
1a5b0 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f  is accessible to
1a5c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1a5d0 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74  via the.** [last
1a5e0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20  _insert_rowid() 
1a5f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
1a600 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
1a610 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72  te thread perfor
1a620 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54  ms a new [INSERT
1a630 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  ] on the same.**
1a640 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a650 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b  tion while the [
1a660 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
1a670 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20  ert_rowid()].** 
1a680 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
1a690 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
1a6a0 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
1a6b0 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a  sert [rowid],.**
1a6c0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
1a6d0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1a6e0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
1a6f0 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20  _rowid()] is.** 
1a700 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
1a710 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61  d might not equa
1a720 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64  l either the old
1a730 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c   or the new.** l
1a740 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
1a750 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  d]..*/.sqlite3_i
1a760 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
1a770 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
1a780 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1a790 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 74   CAPI3REF: Set t
1a7a0 68 65 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  he Last Insert R
1a7b0 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d  owid value..** M
1a7c0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1a7d0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1a7e0 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74  _set_last_insert
1a7f0 5f 72 6f 77 69 64 28 44 2c 20 52 29 20 6d 65 74  _rowid(D, R) met
1a800 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65 20 61  hod allows the a
1a810 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a  pplication to.**
1a820 20 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 72   set the value r
1a830 65 74 75 72 6e 65 64 20 62 79 20 63 61 6c 6c 69  eturned by calli
1a840 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  ng sqlite3_last_
1a850 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
1a860 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75 74  to R .** without
1a870 20 69 6e 73 65 72 74 69 6e 67 20 61 20 72 6f 77   inserting a row
1a880 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
1a890 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  se..*/.void sqli
1a8a0 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73  te3_set_last_ins
1a8b0 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
1a8c0 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  3*,sqlite3_int64
1a8d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a8e0 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75  EF: Count The Nu
1a8f0 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
1a900 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ified.** METHOD:
1a910 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1a920 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
1a930 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
1a940 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
1a950 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a  d, inserted or.*
1a960 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  * deleted by the
1a970 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
1a980 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c  ompleted INSERT,
1a990 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
1a9a0 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f  E.** statement o
1a9b0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
1a9c0 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66  onnection specif
1a9d0 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20  ied by the only 
1a9e0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45  parameter..** ^E
1a9f0 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68  xecuting any oth
1aa00 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73  er type of SQL s
1aa10 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
1aa20 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c  t modify the val
1aa30 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
1aa40 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  y this function.
1aa50 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61  .**.** ^Only cha
1aa60 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 74  nges made direct
1aa70 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 54  ly by the INSERT
1aa80 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
1aa90 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  TE statement are
1aaa0 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d  .** considered -
1aab0 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   auxiliary chang
1aac0 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 52  es caused by [CR
1aad0 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
1aae0 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66  riggers], .** [f
1aaf0 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
1ab00 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d  ns] or [REPLACE]
1ab10 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
1ab20 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63  lution are not c
1ab30 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43  ounted..** .** C
1ab40 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
1ab50 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63   that are interc
1ab60 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e  epted by .** [IN
1ab70 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
1ab80 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72   | INSTEAD OF tr
1ab90 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20  iggers] are not 
1aba0 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61  counted. ^The va
1abb0 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64  lue .** returned
1abc0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e   by sqlite3_chan
1abd0 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c  ges() immediatel
1abe0 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52  y after an INSER
1abf0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a  T, UPDATE or .**
1ac00 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
1ac10 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20  t run on a view 
1ac20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20  is always zero. 
1ac30 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64  Only changes mad
1ac40 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61  e to real .** ta
1ac50 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  bles are counted
1ac60 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61  ..**.** Things a
1ac70 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61  re more complica
1ac80 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 74  ted if the sqlit
1ac90 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  e3_changes() fun
1aca0 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63  ction is.** exec
1acb0 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 69  uted while a tri
1acc0 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20  gger program is 
1acd0 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61  running. This ma
1ace0 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a  y happen if the.
1acf0 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20  ** program uses 
1ad00 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
1ad10 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72  QL function], or
1ad20 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63   if some other c
1ad30 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
1ad40 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69  ion invokes sqli
1ad50 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69  te3_changes() di
1ad60 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61  rectly. Essentia
1ad70 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e  lly:.** .** <ul>
1ad80 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66  .**   <li> ^(Bef
1ad90 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74  ore entering a t
1ada0 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74  rigger program t
1adb0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1adc0 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73  d by.**        s
1add0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1ade0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76   function is sav
1adf0 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 72  ed. After the tr
1ae00 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a  igger program .*
1ae10 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69 6e  *        has fin
1ae20 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69  ished, the origi
1ae30 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73  nal value is res
1ae40 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20  tored.)^.** .** 
1ae50 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20    <li> ^(Within 
1ae60 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
1ae70 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55  m each INSERT, U
1ae80 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45  PDATE and DELETE
1ae90 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74   .**        stat
1aea0 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 76  ement sets the v
1aeb0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1aec0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1aed0 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70  () .**        up
1aee0 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73  on completion as
1aef0 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72   normal. Of cour
1af00 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77  se, this value w
1af10 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  ill not include 
1af20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63  .**        any c
1af30 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64  hanges performed
1af40 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 73   by sub-triggers
1af50 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 33  , as the sqlite3
1af60 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20  _changes() .**  
1af70 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c        value will
1af80 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 65   be saved and re
1af90 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 63  stored after eac
1afa0 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61  h sub-trigger ha
1afb0 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c  s run.)^.** </ul
1afc0 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d  >.** .** ^This m
1afd0 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 65  eans that if the
1afe0 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66   changes() SQL f
1aff0 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69  unction (or simi
1b000 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20  lar) is used.** 
1b010 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e 53  by the first INS
1b020 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1b030 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
1b040 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
1b050 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73  , it .** returns
1b060 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 65   the value as se
1b070 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69  t when the calli
1b080 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67  ng statement beg
1b090 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  an executing..**
1b0a0 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 20   ^If it is used 
1b0b0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72  by the second or
1b0c0 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 68   subsequent such
1b0d0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
1b0e0 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20  n a trigger .** 
1b0f0 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c  program, the val
1b100 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c  ue returned refl
1b110 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20  ects the number 
1b120 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64  of rows modified
1b130 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76   by the .** prev
1b140 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44  ious INSERT, UPD
1b150 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
1b160 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
1b170 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
1b180 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
1b190 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
1b1a0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
1b1b0 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
1b1c0 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
1b1d0 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
1b1e0 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
1b1f0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
1b200 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
1b210 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
1b220 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
1b230 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b240 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
1b250 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
1b260 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
1b270 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1b280 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
1b290 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
1b2a0 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
1b2b0 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
1b2c0 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
1b2d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
1b2e0 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
1b2f0 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d  ws Modified.** M
1b300 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1b310 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
1b320 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
1b330 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
1b340 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d  rows inserted, m
1b350 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65  odified or.** de
1b360 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e  leted by all [IN
1b370 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20  SERT], [UPDATE] 
1b380 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
1b390 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64  ements completed
1b3a0 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61  .** since the da
1b3b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b3c0 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e  n was opened, in
1b3d0 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78  cluding those ex
1b3e0 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72  ecuted as.** par
1b3f0 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f  t of trigger pro
1b400 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e  grams. ^Executin
1b410 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65  g any other type
1b420 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
1b430 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66  t.** does not af
1b440 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72  fect the value r
1b450 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1b460 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1b470 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e  ()..** .** ^Chan
1b480 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74  ges made as part
1b490 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79   of [foreign key
1b4a0 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e   actions] are in
1b4b0 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a  cluded in the.**
1b4c0 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73   count, but thos
1b4d0 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f  e made as part o
1b4e0 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72  f REPLACE constr
1b4f0 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  aint resolution 
1b500 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61  are.** not. ^Cha
1b510 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
1b520 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70  hat are intercep
1b530 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f  ted by INSTEAD O
1b540 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61  F triggers .** a
1b550 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a  re not counted..
1b560 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  ** .** See also 
1b570 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
1b580 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
1b590 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
1b5a0 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
1b5b0 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
1b5c0 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
1b5d0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
1b5e0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
1b5f0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
1b600 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
1b610 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b620 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
1b630 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1b640 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
1b650 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
1b660 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
1b670 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
1b680 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
1b690 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1b6a0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
1b6b0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1b6c0 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
1b6d0 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
1b6e0 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48  ng Query.** METH
1b6f0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1b700 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
1b710 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
1b720 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
1b730 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
1b740 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
1b750 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
1b760 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
1b770 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
1b780 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
1b790 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
1b7a0 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
1b7b0 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
1b7c0 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
1b7d0 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
1b7e0 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
1b7f0 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
1b800 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
1b810 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  ately..**.** ^It
1b820 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
1b830 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
1b840 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
1b850 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
1b860 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
1b870 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
1b880 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
1b890 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
1b8a0 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
1b8b0 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
1b8c0 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
1b8d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b8e0 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
1b8f0 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
1b900 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
1b910 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1b920 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
1b930 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
1b940 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
1b950 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
1b960 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
1b970 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1b980 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
1b990 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
1b9a0 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
1b9b0 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
1b9c0 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
1b9d0 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
1b9e0 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
1b9f0 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  * ^An SQL operat
1ba00 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
1ba10 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
1ba20 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
1ba30 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74  RRUPT]..** ^If t
1ba40 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
1ba50 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
1ba60 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
1ba70 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
1ba80 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
1ba90 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
1baa0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
1bab0 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
1bac0 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
1bad0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
1bae0 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
1baf0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
1bb00 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69  errupt(D) call i
1bb10 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69  s in effect unti
1bb20 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20  l all currently 
1bb30 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
1bb40 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61  tatements on [da
1bb50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1bb60 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20  n] D complete.  
1bb70 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61  ^Any new SQL sta
1bb80 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
1bb90 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
1bba0 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
1bbb0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61  terrupt() call a
1bbc0 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a  nd before the .*
1bbd0 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  * running statem
1bbe0 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72  ents reaches zer
1bbf0 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65  o are interrupte
1bc00 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64  d as if they had
1bc10 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67   been.** running
1bc20 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71   prior to the sq
1bc30 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1bc40 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51  ) call.  ^New SQ
1bc50 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1bc60 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
1bc70 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
1bc80 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
1bc90 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
1bca0 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
1bcb0 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
1bcc0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
1bcd0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71  ** ^A call to sq
1bce0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1bcf0 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77  D) that occurs w
1bd00 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hen there are no
1bd10 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1bd20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20  statements is a 
1bd30 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f  no-op and has no
1bd40 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
1bd50 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
1bd60 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
1bd70 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
1bd80 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1bd90 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76 6f 69   returns..*/.voi
1bda0 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  d sqlite3_interr
1bdb0 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  upt(sqlite3*);..
1bdc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1bdd0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
1bde0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73  SQL Statement Is
1bdf0 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20   Complete.**.** 
1be00 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1be10 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67  re useful during
1be20 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e   command-line in
1be30 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  put to determine
1be40 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   if the.** curre
1be50 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78  ntly entered tex
1be60 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20  t seems to form 
1be70 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
1be80 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69  tatement or.** i
1be90 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70  f additional inp
1bea0 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66  ut is needed bef
1beb0 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20  ore sending the 
1bec0 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c  text into.** SQL
1bed0 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e  ite for parsing.
1bee0 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
1bef0 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68  s return 1 if th
1bf00 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a  e input string.*
1bf10 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20  * appears to be 
1bf20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
1bf30 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74  tatement.  ^A st
1bf40 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65  atement is judge
1bf50 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c  d to be.** compl
1bf60 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77  ete if it ends w
1bf70 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20  ith a semicolon 
1bf80 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74  token and is not
1bf90 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a   a prefix of a.*
1bfa0 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52  * well-formed CR
1bfb0 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61  EATE TRIGGER sta
1bfc0 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f  tement.  ^Semico
1bfd0 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d  lons that are em
1bfe0 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a  bedded within.**
1bff0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73   string literals
1c000 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74   or quoted ident
1c010 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63  ifier names or c
1c020 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a  omments are not.
1c030 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74  ** independent t
1c040 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20  okens (they are 
1c050 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65  part of the toke
1c060 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20  n in which they 
1c070 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29  are.** embedded)
1c080 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74   and thus do not
1c090 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74   count as a stat
1c0a0 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72  ement terminator
1c0b0 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a  .  ^Whitespace.*
1c0c0 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74  * and comments t
1c0d0 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66  hat follow the f
1c0e0 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61  inal semicolon a
1c0f0 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  re ignored..**.*
1c100 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
1c110 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68  s return 0 if th
1c120 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69  e statement is i
1c130 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20  ncomplete.  ^If 
1c140 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
1c150 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68  cation fails, th
1c160 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  en SQLITE_NOMEM 
1c170 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
1c180 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1c190 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20  es do not parse 
1c1a0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1c1b0 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20  ts thus.** will 
1c1c0 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61  not detect synta
1c1d0 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65  ctically incorre
1c1e0 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ct SQL..**.** ^(
1c1f0 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f  If SQLite has no
1c200 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a  t been initializ
1c210 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1c220 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
1c230 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76  prior .** to inv
1c240 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  oking sqlite3_co
1c250 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20  mplete16() then 
1c260 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
1c270 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
1c280 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
1c290 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   by sqlite3_comp
1c2a0 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68  lete16().  If th
1c2b0 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  at initializatio
1c2c0 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e  n fails,.** then
1c2d0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
1c2e0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
1c2f0 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c  omplete16() will
1c300 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20   be non-zero.** 
1c310 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
1c320 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
1c330 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f   input SQL is co
1c340 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  mplete.)^.**.** 
1c350 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
1c360 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29  lite3_complete()
1c370 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
1c380 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
1c390 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
1c3a0 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
1c3b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
1c3c0 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61  e16()] must be a
1c3d0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1c3e0 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
1c3f0 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
1c400 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73   order..*/.int s
1c410 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
1c420 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29  const char *sql)
1c430 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
1c440 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76  mplete16(const v
1c450 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a  oid *sql);../*.*
1c460 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
1c470 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20  ster A Callback 
1c480 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45  To Handle SQLITE
1c490 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20  _BUSY Errors.** 
1c4a0 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d  KEYWORDS: {busy-
1c4b0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
1c4c0 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d  } {busy handler}
1c4d0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1c4e0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
1c4f0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1c500 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69  ler(D,X,P) routi
1c510 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
1c520 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a  ck function X.**
1c530 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
1c540 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75  nvoked with argu
1c550 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a  ment P whenever.
1c560 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  ** an attempt is
1c570 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20   made to access 
1c580 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
1c590 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1c5a0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1c5b0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e  nnection] D when
1c5c0 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
1c5d0 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
1c5e0 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b  s the table lock
1c5f0 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ed..** The sqlit
1c600 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1c610 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
1c620 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
1c630 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
1c640 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64  y_timeout()] and
1c650 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1c660 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  meout]..**.** ^I
1c670 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
1c680 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
1c690 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
1c6a0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
1c6b0 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20  mmediately upon 
1c6c0 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65  encountering the
1c6d0 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20   lock.  ^If the 
1c6e0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  busy callback.**
1c6f0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
1c700 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1c710 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
1c720 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
1c730 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
1c740 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
1c750 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  o the busy handl
1c760 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  er is a copy of 
1c770 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  the void* pointe
1c780 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  r which.** is th
1c790 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
1c7a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79   to sqlite3_busy
1c7b0 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68  _handler().  ^Th
1c7c0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1c7d0 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79  t to.** the busy
1c7e0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
1c7f0 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  k is the number 
1c800 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68  of times that th
1c810 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68  e busy handler h
1c820 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b  as.** been invok
1c830 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f  ed previously fo
1c840 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69  r the same locki
1c850 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
1c860 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
1c870 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
1c880 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
1c890 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
1c8a0 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
1c8b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
1c8c0 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
1c8d0 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74  is returned.** t
1c8e0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
1c8f0 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  n..** ^If the ca
1c900 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
1c910 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
1c920 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
1c930 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65   is made to acce
1c940 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
1c950 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
1c960 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
1c970 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
1c980 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
1c990 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
1c9a0 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
1c9b0 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
1c9c0 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
1c9d0 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
1c9e0 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
1c9f0 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
1ca00 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
1ca10 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
1ca20 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
1ca30 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
1ca40 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
1ca50 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65  _BUSY].** to the
1ca60 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73   application ins
1ca70 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
1ca80 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61   the .** busy ha
1ca90 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64  ndler..** Consid
1caa0 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
1cab0 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
1cac0 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
1cad0 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
1cae0 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
1caf0 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
1cb00 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
1cb10 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
1cb20 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
1cb30 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
1cb40 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
1cb50 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
1cb60 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
1cb70 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
1cb80 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
1cb90 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
1cba0 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
1cbb0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
1cbc0 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
1cbd0 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
1cbe0 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
1cbf0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
1cc00 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
1cc10 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
1cc20 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
1cc30 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
1cc40 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
1cc50 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
1cc60 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
1cc70 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
1cc80 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
1cc90 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
1cca0 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
1ccb0 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
1ccc0 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
1ccd0 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
1cce0 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
1ccf0 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
1cd00 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
1cd10 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  d..**.** ^The de
1cd20 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62  fault busy callb
1cd30 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ack is NULL..**.
1cd40 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
1cd50 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
1cd60 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66  busy handler def
1cd70 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ined for each.**
1cd80 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1cd90 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67  ction].  Setting
1cda0 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
1cdb0 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a  ler clears any.*
1cdc0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  * previously set
1cdd0 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f   handler.)^  ^No
1cde0 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
1cdf0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
1ce00 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65  meout()].** or e
1ce10 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d  valuating [PRAGM
1ce20 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e  A busy_timeout=N
1ce30 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68  ] will change th
1ce40 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65  e.** busy handle
1ce50 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72  r and thus clear
1ce60 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20   any previously 
1ce70 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72  set busy handler
1ce80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79  ..**.** The busy
1ce90 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
1cea0 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63   not take any ac
1ceb0 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69  tions which modi
1cec0 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  fy the.** databa
1ced0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1cee0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
1cef0 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e  usy handler.  In
1cf00 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a   other words,.**
1cf10 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1cf20 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  r is not reentra
1cf30 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63  nt.  Any such ac
1cf40 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20  tions.** result 
1cf50 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
1cf60 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20  avior..** .** A 
1cf70 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73  busy handler mus
1cf80 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
1cf90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1cfa0 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61  ion.** or [prepa
1cfb0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
1cfc0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1cfd0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f  busy handler..*/
1cfe0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
1cff0 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  y_handler(sqlite
1d000 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  3*,int(*)(void*,
1d010 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  int),void*);../*
1d020 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
1d030 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
1d040 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1d050 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
1d060 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b  routine sets a [
1d070 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1d080 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64  dler | busy hand
1d090 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73  ler] that sleeps
1d0a0 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66  .** for a specif
1d0b0 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69  ied amount of ti
1d0c0 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20  me when a table 
1d0d0 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65  is locked.  ^The
1d0e0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c   handler.** will
1d0f0 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20   sleep multiple 
1d100 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c  times until at l
1d110 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
1d120 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
1d130 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d  ng.** have accum
1d140 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20  ulated.  ^After 
1d150 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
1d160 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
1d170 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68  eeping,.** the h
1d180 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30  andler returns 0
1d190 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73   which causes [s
1d1a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
1d1b0 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  o return.** [SQL
1d1c0 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a  ITE_BUSY]..**.**
1d1d0 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72   ^Calling this r
1d1e0 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
1d1f0 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
1d200 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
1d210 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20  ro.** turns off 
1d220 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  all busy handler
1d230 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  s..**.** ^(There
1d240 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
1d250 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
1d260 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  er for a particu
1d270 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
1d280 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20   connection] at 
1d290 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74  any given moment
1d2a0 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75  .  If another bu
1d2b0 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61  sy handler.** wa
1d2c0 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e  s defined  (usin
1d2d0 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1d2e0 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
1d2f0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
1d300 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
1d310 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
1d320 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
1d330 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
1d340 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73  so:  [PRAGMA bus
1d350 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e  y_timeout].*/.in
1d360 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
1d370 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
1d380 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
1d390 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
1d3a0 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
1d3b0 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
1d3c0 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ies.** METHOD: s
1d3d0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69  qlite3.**.** Thi
1d3e0 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e  s is a legacy in
1d3f0 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20  terface that is 
1d400 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61  preserved for ba
1d410 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1d420 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66  ility..** Use of
1d430 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
1d440 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64  is not recommend
1d450 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ed..**.** Defini
1d460 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
1d470 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
1d480 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
1d490 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
1d4a0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1d4b0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
1d4c0 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
1d4d0 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
1d4e0 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
1d4f0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
1d500 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
1d510 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
1d520 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
1d530 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
1d540 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
1d550 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
1d560 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
1d570 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
1d580 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
1d590 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
1d5a0 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
1d5b0 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
1d5c0 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
1d5d0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
1d5e0 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
1d5f0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
1d600 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1d610 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
1d620 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
1d630 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1d640 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
1d650 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
1d660 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
1d670 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
1d680 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
1d690 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
1d6a0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
1d6b0 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
1d6c0 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
1d6d0 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
1d6e0 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
1d6f0 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
1d700 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
1d710 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
1d720 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
1d730 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
1d740 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
1d750 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
1d760 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1d770 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
1d780 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
1d790 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1d7a0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
1d7b0 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1d7c0 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
1d7d0 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
1d7e0 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
1d7f0 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
1d800 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
1d810 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
1d820 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
1d830 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
1d840 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1d850 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
1d860 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
1d870 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1d880 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20  ()]..**.** ^(As 
1d890 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
1d8a0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
1d8b0 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
1d8c0 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
1d8d0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1d8e0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1d8f0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
1d900 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
1d910 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
1d920 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1d930 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
1d940 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
1d950 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
1d960 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
1d970 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
1d980 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
1d990 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1d9a0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
1d9b0 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
1d9c0 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
1d9d0 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
1d9e0 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
1d9f0 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
1da00 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
1da10 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
1da20 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
1da30 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
1da40 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
1da50 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
1da60 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
1da70 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1da80 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1da90 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
1daa0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1dab0 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
1dac0 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
1dad0 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
1dae0 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
1daf0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1db00 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
1db10 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1db20 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
1db30 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1db40 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
1db50 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1db60 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
1db70 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
1db80 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
1db90 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
1dba0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
1dbb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1dbc0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1dbd0 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
1dbe0 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
1dbf0 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
1dc00 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
1dc10 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
1dc20 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1dc30 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
1dc40 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
1dc50 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72   and returns a r
1dc60 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
1dc70 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
1dc80 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
1dc90 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1dca0 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63  After the applic
1dcb0 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ation has finish
1dcc0 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75  ed with the resu
1dcd0 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  lt from sqlite3_
1dce0 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20  get_table(),.** 
1dcf0 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65  it must pass the
1dd00 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f   result table po
1dd10 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
1dd20 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
1dd30 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c   order to.** rel
1dd40 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
1dd50 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65  that was malloce
1dd60 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
1dd70 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73  he way the.** [s
1dd80 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1dd90 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20   happens within 
1dda0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1ddb0 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  e(), the calling
1ddc0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
1ddd0 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
1dde0 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
1ddf0 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  )] directly.  On
1de00 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ly.** [sqlite3_f
1de10 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
1de20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
1de30 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
1de40 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
1de50 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1de60 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
1de70 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
1de80 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
1de90 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
1dea0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
1deb0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
1dec0 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
1ded0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
1dee0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
1def0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
1df00 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
1df10 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
1df20 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
1df30 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
1df40 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
1df50 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
1df60 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
1df70 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
1df80 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
1df90 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
1dfa0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
1dfb0 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
1dfc0 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
1dfd0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
1dfe0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1dff0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
1e000 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a  3_errmsg()]..*/.
1e010 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
1e020 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  table(.  sqlite3
1e030 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
1e040 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
1e050 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
1e060 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a  ar *zSql,     /*
1e070 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
1e080 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ated */.  char *
1e090 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20  **pazResult,    
1e0a0 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68  /* Results of th
1e0b0 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74  e query */.  int
1e0c0 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20   *pnRow,        
1e0d0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1e0e0 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74  result rows writ
1e0f0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e  ten here */.  in
1e100 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20  t *pnColumn,    
1e110 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
1e120 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20   result columns 
1e130 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1e140 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73    char **pzErrms
1e150 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72  g       /* Error
1e160 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
1e170 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c  e */.);.void sql
1e180 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1e190 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
1e1a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e1b0 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
1e1c0 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
1e1d0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
1e1e0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
1e1f0 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  rk-alikes of the
1e200 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
1e210 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
1e220 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
1e230 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
1e240 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1e250 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73  s understand mos
1e260 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20  t of the common 
1e270 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  K&R formatting o
1e280 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20  ptions,.** plus 
1e290 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
1e2a0 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72  non-standard for
1e2b0 6d 61 74 73 2c 20 64 65 74 61 69 6c 65 64 20 62  mats, detailed b
1e2c0 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  elow..** Note th
1e2d0 61 74 20 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d  at some of the m
1e2e0 6f 72 65 20 6f 62 73 63 75 72 65 20 66 6f 72 6d  ore obscure form
1e2f0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66  atting options f
1e300 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d  rom recent.** C-
1e310 6c 69 62 72 61 72 79 20 73 74 61 6e 64 61 72 64  library standard
1e320 73 20 61 72 65 20 6f 6d 69 74 74 65 64 20 66 72  s are omitted fr
1e330 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e  om this implemen
1e340 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  tation..**.** ^T
1e350 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
1e360 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
1e370 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
1e380 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
1e390 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
1e3a0 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
1e3b0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
1e3c0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65  alloc()]..** The
1e3d0 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
1e3e0 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72  d by these two r
1e3f0 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62  outines should b
1e400 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79  e.** released by
1e410 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1e420 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e  ].  ^Both routin
1e430 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e  es return a.** N
1e440 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b  ULL pointer if [
1e450 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1e460 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  ] is unable to a
1e470 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a  llocate enough.*
1e480 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * memory to hold
1e490 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
1e4a0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tring..**.** ^(T
1e4b0 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  he sqlite3_snpri
1e4c0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
1e4d0 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70   similar to "snp
1e4e0 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a  rintf()" from.**
1e4f0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1e500 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65  library.  The re
1e510 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20  sult is written 
1e520 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66  into the.** buff
1e530 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74  er supplied as t
1e540 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1e550 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69  ter whose size i
1e560 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68  s given by.** th
1e570 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1e580 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  r. Note that the
1e590 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a   order of the.**
1e5a0 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d   first two param
1e5b0 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65  eters is reverse
1e5c0 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28  d from snprintf(
1e5d0 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e  ).)^  This is an
1e5e0 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61  .** historical a
1e5f0 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e  ccident that can
1e600 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74  not be fixed wit
1e610 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a  hout breaking.**
1e620 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1e630 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74  tibility.  ^(Not
1e640 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69  e also that sqli
1e650 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1e660 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
1e670 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65  ter to its buffe
1e680 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
1e690 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
1e6a0 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c  aracters actuall
1e6b0 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  y written into t
1e6c0 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65  he buffer.)^  We
1e6d0 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74   admit that.** t
1e6e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
1e6f0 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20  racters written 
1e700 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20  would be a more 
1e710 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a  useful return.**
1e720 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61   value but we ca
1e730 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20  nnot change the 
1e740 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1e750 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
1e760 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68  tf().** now with
1e770 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d  out breaking com
1e780 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
1e790 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  * ^As long as th
1e7a0 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
1e7b0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
1e7c0 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
1e7d0 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
1e7e0 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
1e7f0 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
1e800 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
1e810 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70   ^The first.** p
1e820 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
1e830 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
1e840 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
1e850 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
1e860 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
1e870 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
1e880 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
1e890 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
1e8a0 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
1e8b0 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
1e8c0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
1e8d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73   ^The sqlite3_vs
1e8e0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
1e8f0 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76  e is a varargs v
1e900 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  ersion of sqlite
1e910 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a  3_snprintf()..**
1e920 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1e930 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
1e940 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
1e950 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
1e960 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
1e970 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
1e980 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
1e990 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
1e9a0 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
1e9b0 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20  tf() formatting 
1e9c0 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
1e9d0 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
1e9e0 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
1e9f0 22 2c 20 22 25 51 22 2c 20 22 25 77 22 20 61 6e  ", "%Q", "%w" an
1ea00 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a  d "%z" options..
1ea10 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f  **.** ^(The %q o
1ea20 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1ea30 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73   %s in that it s
1ea40 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c  ubstitutes a nul
1ea50 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
1ea60 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
1ea70 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
1ea80 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
1ea90 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
1eaa0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
1eab0 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
1eac0 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
1ead0 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42  ng literal.)^  B
1eae0 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20  y doubling each 
1eaf0 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65  '\''.** characte
1eb00 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61  r it escapes tha
1eb10 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20  t character and 
1eb20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20  allows it to be 
1eb30 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a  inserted into.**
1eb40 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a   the string..**.
1eb50 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
1eb60 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e  assume the strin
1eb70 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74  g variable zText
1eb80 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61   contains text a
1eb90 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1eba0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1ebb0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65  e>.**  char *zTe
1ebc0 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70  xt = "It's a hap
1ebd0 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70  py day!";.** </p
1ebe0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1ebf0 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75  .**.** One can u
1ec00 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20  se this text in 
1ec10 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1ec20 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1ec30 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1ec40 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1ec50 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
1ec60 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
1ec70 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
1ec80 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a  '%q')", zText);.
1ec90 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
1eca0 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
1ecb0 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
1ecc0 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
1ecd0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1ece0 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  te>.**.** Becaus
1ecf0 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20  e the %q format 
1ed00 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20  string is used, 
1ed10 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74  the '\'' charact
1ed20 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69  er in zText.** i
1ed30 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68  s escaped and th
1ed40 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20  e SQL generated 
1ed50 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1ed60 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1ed70 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1ed80 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1ed90 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61  LUES('It''s a ha
1eda0 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f  ppy day!').** </
1edb0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1edc0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  >.**.** This is 
1edd0 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65  correct.  Had we
1ede0 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64   used %s instead
1edf0 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65   of %q, the gene
1ee00 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75  rated SQL.** wou
1ee10 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c  ld have looked l
1ee20 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
1ee30 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1ee40 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
1ee50 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
1ee60 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  'It's a happy da
1ee70 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  y!');.** </pre><
1ee80 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1ee90 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65  ** This second e
1eea0 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c  xample is an SQL
1eeb0 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20   syntax error.  
1eec0 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c  As a general rul
1eed0 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20  e you should.** 
1eee0 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e  always use %q in
1eef0 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e  stead of %s when
1ef00 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20   inserting text 
1ef10 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  into a string li
1ef20 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  teral..**.** ^(T
1ef30 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72  he %Q option wor
1ef40 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70  ks like %q excep
1ef50 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73  t it also adds s
1ef60 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f  ingle quotes aro
1ef70 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69  und.** the outsi
1ef80 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20  de of the total 
1ef90 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  string.  Additio
1efa0 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61  nally, if the pa
1efb0 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a  rameter in the.*
1efc0 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20  * argument list 
1efd0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1efe0 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65  r, %Q substitute
1eff0 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c  s the text "NULL
1f000 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69  " (without.** si
1f010 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20  ngle quotes).)^ 
1f020 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
1f030 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a  , one could say:
1f040 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1f050 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1f060 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
1f070 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
1f080 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
1f090 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29  UES(%Q)", zText)
1f0a0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1f0b0 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1f0c0 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1f0d0 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1f0e0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1f0f0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
1f100 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20  code above will 
1f110 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74  render a correct
1f120 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1f130 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61  n the zSQL.** va
1f140 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74  riable even if t
1f150 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c  he zText variabl
1f160 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e is a NULL poin
1f170 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ter..**.** ^(The
1f180 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%w" formatting
1f190 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20   option is like 
1f1a0 22 25 71 22 20 65 78 63 65 70 74 20 74 68 61 74  "%q" except that
1f1b0 20 69 74 20 65 78 70 65 63 74 73 20 74 6f 0a 2a   it expects to.*
1f1c0 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 77  * be contained w
1f1d0 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f  ithin double-quo
1f1e0 74 65 73 20 69 6e 73 74 65 61 64 20 6f 66 20 73  tes instead of s
1f1f0 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e  ingle quotes, an
1f200 64 20 69 74 0a 2a 2a 20 65 73 63 61 70 65 73 20  d it.** escapes 
1f210 74 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65  the double-quote
1f220 20 63 68 61 72 61 63 74 65 72 20 69 6e 73 74 65   character inste
1f230 61 64 20 6f 66 20 74 68 65 20 73 69 6e 67 6c 65  ad of the single
1f240 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63  -quote.** charac
1f250 74 65 72 2e 29 5e 20 20 54 68 65 20 22 25 77 22  ter.)^  The "%w"
1f260 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1f270 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66  on is intended f
1f280 6f 72 20 73 61 66 65 6c 79 20 69 6e 73 65 72 74  or safely insert
1f290 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64  ing.** table and
1f2a0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e   column names in
1f2b0 74 6f 20 61 20 63 6f 6e 73 74 72 75 63 74 65 64  to a constructed
1f2c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
1f2d0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22  **.** ^(The "%z"
1f2e0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1f2f0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25  on works like "%
1f300 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a  s" but with the.
1f310 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  ** addition that
1f320 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e   after the strin
1f330 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20  g has been read 
1f340 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a  and copied into.
1f350 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b  ** the result, [
1f360 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1f370 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  is called on the
1f380 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e   input string.)^
1f390 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .*/.char *sqlite
1f3a0 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
1f3b0 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72  char*,...);.char
1f3c0 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
1f3d0 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
1f3e0 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a  va_list);.char *
1f3f0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1f400 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
1f410 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68   char*, ...);.ch
1f420 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70  ar *sqlite3_vsnp
1f430 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
1f440 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
1f450 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  list);../*.** CA
1f460 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
1f470 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
1f480 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
1f490 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
1f4a0 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
1f4b0 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
1f4c0 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
1f4d0 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
1f4e0 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
1f4f0 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
1f500 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
1f510 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
1f520 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
1f530 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
1f540 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
1f550 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
1f560 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
1f570 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
1f580 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
1f590 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
1f5a0 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1f5b0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
1f5c0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1f5d0 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
1f5e0 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
1f5f0 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
1f600 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
1f610 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
1f620 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
1f630 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
1f640 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
1f650 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
1f660 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
1f670 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
1f680 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1f690 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
1f6a0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
1f6b0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
1f6c0 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
1f6d0 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
1f6e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1f6f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1f700 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75  _malloc64(N) rou
1f710 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20  tine works just 
1f720 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  like.** sqlite3_
1f730 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74  malloc(N) except
1f740 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e   that N is an un
1f750 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e  signed 64-bit in
1f760 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
1f770 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d   of a signed 32-
1f780 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  bit integer..**.
1f790 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
1f7a0 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
1f7b0 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
1f7c0 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
1f7d0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
1f7e0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1f7f0 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
1f800 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
1f810 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
1f820 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e  ht be reused.  ^
1f830 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
1f840 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
1f850 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
1f860 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
1f870 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
1f880 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
1f890 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
1f8a0 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
1f8b0 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
1f8c0 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
1f8d0 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
1f8e0 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
1f8f0 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
1f900 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
1f910 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
1f920 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
1f930 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
1f940 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
1f950 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
1f960 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
1f970 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
1f980 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
1f990 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
1f9a0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
1f9b0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1f9c0 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
1f9d0 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
1f9e0 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
1f9f0 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
1fa00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1fa10 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1fa20 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  loc()..**.** ^Th
1fa30 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
1fa40 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  c(X,N) interface
1fa50 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
1fa60 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
1fa70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1fa80 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73   X to be at leas
1fa90 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49  t N bytes..** ^I
1faa0 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65  f the X paramete
1fab0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1fac0 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20  lloc(X,N).** is 
1fad0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1fae0 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
1faf0 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
1fb00 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1fb10 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a  te3_malloc(N)..*
1fb20 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61  * ^If the N para
1fb30 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1fb40 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73  _realloc(X,N) is
1fb50 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
1fb60 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
1fb70 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
1fb80 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
1fb90 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1fba0 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71  _free(X)..** ^sq
1fbb0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1fbc0 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  N) returns a poi
1fbd0 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
1fbe0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
1fbf0 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
1fc00 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
1fc10 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65  LL if insufficie
1fc20 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61  nt memory is ava
1fc30 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
1fc40 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
1fc50 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1fc60 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
1fc70 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
1fc80 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1fc90 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
1fca0 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
1fcb0 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
1fcc0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1fcd0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1fce0 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61   and the prior a
1fcf0 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65  llocation is fre
1fd00 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  ed..** ^If sqlit
1fd10 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1fd20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
1fd30 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20   N is positive, 
1fd40 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f  then the.** prio
1fd50 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1fd60 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
1fd70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
1fd80 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74  alloc64(X,N) int
1fd90 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68  erfaces works th
1fda0 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c  e same as.** sql
1fdb0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1fdc0 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
1fdd0 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69  is a 64-bit unsi
1fde0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73  gned integer ins
1fdf0 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d  tead.** of a 32-
1fe00 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
1fe10 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20  er..**.** ^If X 
1fe20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  is a memory allo
1fe30 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c  cation previousl
1fe40 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
1fe50 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1fe60 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ,.** sqlite3_mal
1fe70 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33  loc64(), sqlite3
1fe80 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73  _realloc(), or s
1fe90 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1fea0 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  (), then.** sqli
1feb0 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
1fec0 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66  urns the size of
1fed0 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c   that memory all
1fee0 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73  ocation in bytes
1fef0 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20  ..** ^The value 
1ff00 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1ff10 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67  te3_msize(X) mig
1ff20 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  ht be larger tha
1ff30 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20  n the number.** 
1ff40 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74  of bytes request
1ff50 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c  ed when X was al
1ff60 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20  located.  ^If X 
1ff70 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1ff80 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  r then.** sqlite
1ff90 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72  3_msize(X) retur
1ffa0 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70  ns zero.  If X p
1ffb0 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69  oints to somethi
1ffc0 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a  ng that is not.*
1ffd0 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  * the beginning 
1ffe0 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  of memory alloca
1fff0 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70  tion, or if it p
20000 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65  oints to a forme
20010 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d  rly.** valid mem
20020 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
20030 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e  hat has now been
20040 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65   freed, then the
20050 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
20060 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
20070 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
20080 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66  d possibly harmf
20090 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ul..**.** ^The m
200a0 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
200b0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
200c0 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  (), sqlite3_real
200d0 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
200e0 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e  3_malloc64(), an
200f0 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
20100 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  c64().** is alwa
20110 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
20120 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
20130 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f   boundary, or to
20140 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75   a.** 4 byte bou
20150 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51  ndary if the [SQ
20160 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47  LITE_4_BYTE_ALIG
20170 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70  NED_MALLOC] comp
20180 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
20190 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
201a0 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
201b0 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
201c0 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
201d0 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
201e0 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
201f0 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
20200 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
20210 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
20220 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
20230 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
20240 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
20250 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
20260 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
20270 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
20280 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
20290 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
202a0 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
202b0 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
202c0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
202d0 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73  .10, the Windows
202e0 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
202f0 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68  yer called.** th
20300 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
20310 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
20320 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
20330 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
20340 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
20350 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
20360 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
20370 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
20380 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
20390 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
203a0 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
203b0 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
203c0 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
203d0 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65  tion errors were
203e0 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
203f0 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f  * they were repo
20400 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
20410 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
20420 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
20430 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
20440 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
20450 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
20460 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
20470 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
20480 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
20490 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
204a0 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
204b0 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
204c0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
204d0 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
204e0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
204f0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
20500 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
20510 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
20520 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
20530 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
20540 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
20550 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
20560 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
20570 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
20580 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
20590 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
205a0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
205b0 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
205c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
205d0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
205e0 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
205f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
20600 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e  oc64(sqlite3_uin
20610 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  t64);.void *sqli
20620 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
20630 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  *, int);.void *s
20640 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
20650 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f  (void*, sqlite3_
20660 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71  uint64);.void sq
20670 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
20680 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  );.sqlite3_uint6
20690 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  4 sqlite3_msize(
206a0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
206b0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
206c0 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
206d0 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  tics.**.** SQLit
206e0 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65  e provides these
206f0 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20   two interfaces 
20700 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e  for reporting on
20710 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f   the status.** o
20720 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
20730 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
20740 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
20750 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
20760 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c  ()].** routines,
20770 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20   which form the 
20780 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
20790 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
207a0 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stem..**.** ^The
207b0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
207c0 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65  _used()] routine
207d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
207e0 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
207f0 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
20800 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  tly outstanding 
20810 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
20820 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68  t freed)..** ^Th
20830 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
20840 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72  y_highwater()] r
20850 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
20860 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61  he maximum.** va
20870 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
20880 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73  memory_used()] s
20890 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61  ince the high-wa
208a0 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20  ter mark.** was 
208b0 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68  last reset.  ^Th
208c0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
208d0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
208e0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
208f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
20900 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
20910 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65   include any ove
20920 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62  rhead.** added b
20930 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20  y SQLite in its 
20940 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
20950 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
20960 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74  c()],.** but not
20970 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
20980 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72  by the any under
20990 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62  lying system lib
209a0 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  rary.** routines
209b0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d   that [sqlite3_m
209c0 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c  alloc()] may cal
209d0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
209e0 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20  mory high-water 
209f0 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f  mark is reset to
20a00 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
20a10 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ue of.** [sqlite
20a20 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
20a30 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
20a40 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  the parameter to
20a50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
20a60 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
20a70 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20   is true.  ^The 
20a80 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
20a90 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  * by [sqlite3_me
20aa0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
20ab0 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77  )] is the high-w
20ac0 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69  ater mark.** pri
20ad0 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
20ae0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
20af0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
20b00 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c  _used(void);.sql
20b10 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
20b20 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
20b30 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
20b40 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
20b50 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
20b60 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
20b70 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
20b80 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
20b90 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
20ba0 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
20bb0 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
20bc0 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
20bd0 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
20be0 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
20bf0 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
20c00 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
20c10 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
20c20 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
20c30 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
20c40 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
20c50 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
20c60 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
20c70 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
20c80 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
20c90 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
20ca0 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
20cb0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
20cc0 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
20cd0 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
20ce0 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
20cf0 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
20d00 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
20d10 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
20d20 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
20d30 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70  r P..** ^The P p
20d40 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20  arameter can be 
20d50 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
20d60 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72  **.** ^If this r
20d70 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62  outine has not b
20d80 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63  een previously c
20d90 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20  alled or if the 
20da0 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c  previous.** call
20db0 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e   had N less than
20dc0 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70   one or a NULL p
20dd0 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68  ointer for P, th
20de0 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a  en the PRNG is.*
20df0 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72  * seeded using r
20e00 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
20e10 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ed from the xRan
20e20 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
20e30 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74  f.** the default
20e40 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
20e50 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  bject..** ^If th
20e60 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
20e70 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
20e80 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72  had an N of 1 or
20e90 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e   more and a.** n
20ea0 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74  on-NULL P then t
20eb0 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  he pseudo-random
20ec0 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65  ness is generate
20ed0 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20  d.** internally 
20ee0 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f  and without reco
20ef0 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c  urse to the [sql
20f00 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f  ite3_vfs] xRando
20f10 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e  mness.** method.
20f20 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
20f30 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
20f40 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
20f50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
20f60 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
20f70 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
20f80 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ks.** METHOD: sq
20f90 6c 69 74 65 33 0a 2a 2a 20 4b 45 59 57 4f 52 44  lite3.** KEYWORD
20fa0 53 3a 20 7b 61 75 74 68 6f 72 69 7a 65 72 20 63  S: {authorizer c
20fb0 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a 20 5e  allback}.**.** ^
20fc0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
20fd0 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72  isters an author
20fe0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
20ff0 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
21000 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
21010 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
21020 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
21030 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
21040 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
21050 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
21060 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
21070 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
21080 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
21090 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
210a0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
210b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
210c0 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
210d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
210e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ], [sqlite3_prep
210f0 61 72 65 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  are16()], [sqlit
21100 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
21110 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  )],.** and [sqli
21120 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
21130 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75  ()].  ^At variou
21140 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
21150 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
21160 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
21170 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
21180 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
21190 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
211a0 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
211b0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
211c0 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
211d0 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
211e0 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
211f0 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
21200 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
21210 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
21220 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
21230 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
21240 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
21250 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
21260 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
21270 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
21280 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
21290 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
212a0 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
212b0 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
212c0 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
212d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
212e0 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
212f0 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
21300 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
21310 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
21320 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
21330 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
21340 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
21350 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
21360 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
21370 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
21380 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
21390 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
213a0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
213b0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
213c0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
213d0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
213e0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
213f0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
21400 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
21410 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
21420 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
21430 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68  sted is ok.  ^Wh
21440 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
21450 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
21460 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
21470 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
21480 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
21490 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
214a0 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
214b0 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
214c0 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
214d0 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
214e0 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
214f0 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
21500 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
21510 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
21520 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21530 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
21540 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
21550 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
21560 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
21570 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
21580 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ce. ^The second 
21590 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
215a0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
215b0 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49  an integer [SQLI
215c0 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
215d0 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
215e0 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72  ifies.** the par
215f0 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74  ticular action t
21600 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
21610 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f   ^The third thro
21620 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
21630 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
21640 61 6c 6c 62 61 63 6b 20 61 72 65 20 65 69 74 68  allback are eith
21650 65 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  er NULL pointers
21660 20 6f 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   or zero-termina
21670 74 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 74  ted strings.** t
21680 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
21690 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61  tional details a
216a0 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
216b0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
216c0 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
216d0 73 20 6d 75 73 74 20 61 6c 77 61 79 73 20 62 65  s must always be
216e0 20 70 72 65 70 61 72 65 64 20 74 6f 20 65 6e 63   prepared to enc
216f0 6f 75 6e 74 65 72 20 61 20 4e 55 4c 4c 20 70 6f  ounter a NULL po
21700 69 6e 74 65 72 20 69 6e 20 61 6e 79 0a 2a 2a 20  inter in any.** 
21710 6f 66 20 74 68 65 20 74 68 69 72 64 20 74 68 72  of the third thr
21720 6f 75 67 68 20 74 68 65 20 73 69 78 74 68 20 70  ough the sixth p
21730 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
21740 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63   authorization c
21750 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
21760 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
21770 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45  de is [SQLITE_RE
21780 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63  AD].** and the c
21790 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
217a0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
217b0 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  then the.** [pre
217c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
217d0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
217e0 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62  nstructed to sub
217f0 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c  stitute.** a NUL
21800 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65  L value in place
21810 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
21820 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20  lumn that would 
21830 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61  have.** been rea
21840 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  d if [SQLITE_OK]
21850 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e   had been return
21860 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  ed.  The [SQLITE
21870 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75  _IGNORE].** retu
21880 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  rn can be used t
21890 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73  o deny an untrus
218a0 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20  ted user access 
218b0 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a  to individual.**
218c0 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61   columns of a ta
218d0 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ble..** ^When a 
218e0 74 61 62 6c 65 20 69 73 20 72 65 66 65 72 65 6e  table is referen
218f0 63 65 64 20 62 79 20 61 20 5b 53 45 4c 45 43 54  ced by a [SELECT
21900 5d 20 62 75 74 20 6e 6f 20 63 6f 6c 75 6d 6e 20  ] but no column 
21910 76 61 6c 75 65 73 20 61 72 65 0a 2a 2a 20 65 78  values are.** ex
21920 74 72 61 63 74 65 64 20 66 72 6f 6d 20 74 68 61  tracted from tha
21930 74 20 74 61 62 6c 65 20 28 66 6f 72 20 65 78 61  t table (for exa
21940 6d 70 6c 65 20 69 6e 20 61 20 71 75 65 72 79 20  mple in a query 
21950 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c 45 43 54 20  like.** "SELECT 
21960 63 6f 75 6e 74 28 2a 29 20 46 52 4f 4d 20 74 61  count(*) FROM ta
21970 62 22 29 20 74 68 65 6e 20 74 68 65 20 5b 53 51  b") then the [SQ
21980 4c 49 54 45 5f 52 45 41 44 5d 20 61 75 74 68 6f  LITE_READ] autho
21990 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
219a0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  * is invoked onc
219b0 65 20 66 6f 72 20 74 68 61 74 20 74 61 62 6c 65  e for that table
219c0 20 77 69 74 68 20 61 20 63 6f 6c 75 6d 6e 20 6e   with a column n
219d0 61 6d 65 20 74 68 61 74 20 69 73 20 61 6e 20 65  ame that is an e
219e0 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  mpty string..** 
219f0 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
21a00 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  ode is [SQLITE_D
21a10 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63  ELETE] and the c
21a20 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
21a30 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ** [SQLITE_IGNOR
21a40 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c  E] then the [DEL
21a50 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70  ETE] operation p
21a60 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a  roceeds but the.
21a70 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  ** [truncate opt
21a80 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69  imization] is di
21a90 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72  sabled and all r
21aa0 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
21ab0 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a  individually..**
21ac0 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
21ad0 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b  r is used when [
21ae0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
21af0 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20  | preparing].** 
21b00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
21b10 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
21b20 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
21b30 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
21b40 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f  statements.** do
21b50 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
21b60 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65  ss data they are
21b70 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
21b80 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
21b90 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20  y do not.** try 
21ba0 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  to execute malic
21bb0 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
21bc0 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
21bd0 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
21be0 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
21bf0 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
21c00 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
21c10 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
21c20 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
21c30 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
21c40 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
21c50 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
21c60 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
21c70 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
21c80 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
21c90 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
21ca0 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
21cb0 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
21cc0 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
21cd0 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
21ce0 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
21cf0 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
21d00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
21d10 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
21d20 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f   that.** disallo
21d30 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78  ws everything ex
21d40 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74  cept [SELECT] st
21d50 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
21d60 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
21d70 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73  t need to proces
21d80 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75  s SQL from untru
21d90 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20  sted sources.** 
21da0 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69  might also consi
21db0 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73  der lowering res
21dc0 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69  ource limits usi
21dd0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
21de0 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69  t()].** and limi
21df0 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69  ting database si
21e00 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61  ze using the [ma
21e10 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
21e20 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64  RAGMA].** in add
21e30 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61  ition to using a
21e40 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  n authorizer..**
21e50 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e  .** ^(Only a sin
21e60 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
21e70 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
21e80 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
21e90 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
21ea0 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
21eb0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
21ec0 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
21ed0 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
21ee0 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44  ious call.)^  ^D
21ef0 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
21f00 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
21f10 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
21f20 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
21f30 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
21f40 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
21f50 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
21f60 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
21f70 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
21f80 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
21f90 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
21fa0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
21fb0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
21fc0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
21fd0 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
21fe0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21ff0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
22000 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
22010 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
22020 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
22030 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
22040 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
22050 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
22060 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  raph..**.** ^Whe
22070 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
22080 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64  re_v2()] is used
22090 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74   to prepare a st
220a0 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20  atement, the.** 
220b0 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20  statement might 
220c0 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64  be re-prepared d
220d0 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
220e0 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
220f0 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
22100 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
22110 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
22120 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
22130 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
22140 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
22150 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
22160 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
22170 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
22180 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
22190 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
221a0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
221b0 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
221c0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
221d0 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
221e0 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
221f0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
22200 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
22210 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
22220 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
22230 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73  3_step()], unles
22240 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69  s.** as stated i
22250 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
22260 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65  aragraph, sqlite
22270 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73  3_step() invokes
22280 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
22290 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72  are_v2() to repr
222a0 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
222b0 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61  t after a schema
222c0 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20   change..*/.int 
222d0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
222e0 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
222f0 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
22300 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
22310 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
22320 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
22330 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
22340 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
22350 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
22360 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
22370 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
22380 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
22390 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
223a0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
223b0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
223c0 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
223d0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
223e0 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
223f0 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
22400 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
22410 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
22420 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
22430 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
22440 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
22450 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
22460 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
22470 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
22480 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
22490 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
224a0 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  n..**.** Note th
224b0 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  at SQLITE_IGNORE
224c0 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73   is also used as
224d0 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73   a [conflict res
224e0 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a  olution mode].**
224f0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74   returned from t
22500 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  he [sqlite3_vtab
22510 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
22520 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64  interface..*/.#d
22530 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
22540 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
22550 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
22560 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
22570 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22580 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
22590 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
225a0 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
225b0 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
225c0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
225d0 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
225e0 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Action Codes.**.
225f0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
22600 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
22610 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
22620 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
22630 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
22640 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
22650 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69  authorize certai
22660 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
22670 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
22680 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
22690 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
226a0 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
226b0 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
226c0 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
226d0 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
226e0 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
226f0 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
22700 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
22710 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
22720 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
22730 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
22740 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
22750 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
22760 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
22770 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
22780 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e  e.** authorized.
22790 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
227a0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
227b0 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
227c0 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
227d0 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
227e0 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
227f0 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
22800 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
22810 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
22820 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
22830 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35  ameter.  ^(The 5
22840 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
22850 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
22860 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
22870 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
22880 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
22890 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29  "temp",.** etc.)
228a0 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29   if applicable.)
228b0 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61  ^  ^The 6th para
228c0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
228d0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
228e0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
228f0 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
22900 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
22910 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
22920 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
22930 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
22940 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
22950 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
22960 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
22970 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
22980 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   code..*/./*****
22990 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
229a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
229b0 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
229c0 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
229d0 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
229e0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
229f0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
22a00 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
22a10 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
22a20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22a30 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
22a40 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
22a50 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22a60 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22a70 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22a80 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
22a90 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
22aa0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
22ab0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
22ac0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22ad0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
22ae0 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
22af0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
22b00 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22b10 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22b20 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
22b30 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
22b40 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
22b50 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22b60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22b70 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
22b80 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
22b90 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
22ba0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22bb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22bc0 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
22bd0 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
22be0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
22bf0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
22c00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22c10 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
22c20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
22c30 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
22c40 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22c50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22c60 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
22c70 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
22c80 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
22c90 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22ca0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22cb0 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
22cc0 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
22cd0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
22ce0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
22cf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22d00 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
22d10 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
22d20 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
22d30 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22d40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22d50 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
22d60 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
22d70 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
22d80 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
22d90 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
22da0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
22db0 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
22dc0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
22dd0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22de0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
22df0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
22e00 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
22e10 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
22e20 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
22e30 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
22e40 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
22e50 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
22e60 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
22e70 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22e80 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
22e90 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
22ea0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
22eb0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
22ec0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22ed0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
22ee0 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
22ef0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
22f00 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22f10 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22f20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
22f30 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
22f40 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22f50 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22f60 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22f70 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
22f80 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
22f90 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
22fa0 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
22fb0 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
22fc0 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
22fd0 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
22fe0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
22ff0 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
23000 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23010 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
23020 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
23030 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
23040 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
23050 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23060 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
23070 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
23080 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
23090 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
230a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
230b0 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
230c0 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
230d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
230e0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
230f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23100 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
23110 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
23120 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
23130 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
23140 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23150 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
23160 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
23170 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
23180 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
23190 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
231a0 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
231b0 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
231c0 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
231d0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
231e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
231f0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
23200 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
23210 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
23220 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
23230 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
23240 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
23250 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
23260 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
23270 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
23280 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
23290 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
232a0 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
232b0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
232c0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
232d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
232e0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
232f0 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
23300 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
23310 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
23320 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
23330 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
23340 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
23350 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20         Function 
23360 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e  Name   */.#defin
23370 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49  e SQLITE_SAVEPOI
23380 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32  NT            32
23390 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
233a0 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20        Savepoint 
233b0 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65  Name  */.#define
233c0 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
233d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
233e0 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
233f0 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  sed */.#define S
23400 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20  QLITE_RECURSIVE 
23410 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20             33   
23420 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
23430 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
23440 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     */../*.** CAP
23450 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
23460 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
23470 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
23480 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
23490 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
234a0 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 20 55  re deprecated. U
234b0 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
234c0 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e 74 65  trace_v2()] inte
234d0 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64  rface.** instead
234e0 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e 65 73   of the routines
234f0 20 64 65 73 63 72 69 62 65 64 20 68 65 72 65 2e   described here.
23500 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
23510 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
23520 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
23530 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
23540 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
23550 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
23560 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
23570 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
23580 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
23590 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
235a0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
235b0 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
235c0 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
235d0 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
235e0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
235f0 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
23600 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
23610 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
23620 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
23630 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
23640 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ith a UTF-8 rend
23650 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20  ering of the.** 
23660 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
23670 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  xt as the statem
23680 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
23690 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
236a0 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69  (Additional sqli
236b0 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
236c0 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75  backs might occu
236d0 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69  r.** as each tri
236e0 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61  ggered subprogra
236f0 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54  m is entered.  T
23700 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72  he callbacks for
23710 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e   triggers.** con
23720 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c  tain a UTF-8 SQL
23730 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64   comment that id
23740 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69  entifies the tri
23750 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  gger.)^.**.** Th
23760 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  e [SQLITE_TRACE_
23770 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70  SIZE_LIMIT] comp
23780 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
23790 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c  can be used to l
237a0 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67  imit.** the leng
237b0 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72  th of [bound par
237c0 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f  ameter] expansio
237d0 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20  n in the output 
237e0 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  of sqlite3_trace
237f0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ()..**.** ^The c
23800 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
23810 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
23820 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
23830 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
23840 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
23850 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
23860 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
23870 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a  lback contains.*
23880 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
23890 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e  tatement text an
238a0 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  d an estimate of
238b0 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
238c0 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20  .** of how long 
238d0 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74  that statement t
238e0 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68  ook to run.  ^Th
238f0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
23900 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e  ck.** time is in
23910 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65   units of nanose
23920 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74  conds, however t
23930 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
23940 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  mentation.** is 
23950 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20  only capable of 
23960 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f  millisecond reso
23970 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69  lution so the si
23980 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63  x least signific
23990 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e  ant.** digits in
239a0 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65   the time are me
239b0 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75  aningless.  Futu
239c0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
239d0 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70  QLite.** might p
239e0 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72  rovide greater r
239f0 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65  esolution on the
23a00 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61   profiler callba
23a10 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ck.  The.** sqli
23a20 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75  te3_profile() fu
23a30 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64  nction is consid
23a40 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61  ered experimenta
23a50 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a  l and is.** subj
23a60 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
23a70 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
23a80 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53   of SQLite..*/.S
23a90 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
23aa0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74   void *sqlite3_t
23ab0 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  race(sqlite3*,. 
23ac0 20 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28    void(*xTrace)(
23ad0 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
23ae0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49  *), void*);.SQLI
23af0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
23b00 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
23b10 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
23b20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
23b30 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
23b40 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
23b50 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
23b60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
23b70 20 54 72 61 63 65 20 45 76 65 6e 74 20 43 6f 64   Trace Event Cod
23b80 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
23b90 53 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a 2a 0a  SQLITE_TRACE.**.
23ba0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
23bb0 74 73 20 69 64 65 6e 74 69 66 79 20 63 6c 61 73  ts identify clas
23bc0 73 65 73 20 6f 66 20 65 76 65 6e 74 73 20 74 68  ses of events th
23bd0 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69 74 6f  at can be monito
23be0 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65  red.** using the
23bf0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
23c00 76 32 28 29 5d 20 74 72 61 63 69 6e 67 20 6c 6f  v2()] tracing lo
23c10 67 69 63 2e 20 20 54 68 65 20 74 68 69 72 64 20  gic.  The third 
23c20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b  argument.** to [
23c30 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
23c40 28 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65 64 20  ()] is an OR-ed 
23c50 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f  combination of o
23c60 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a  ne or more of.**
23c70 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
23c80 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68 65 20  onstants.  ^The 
23c90 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
23ca0 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c  o the trace call
23cb0 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f  back.** is one o
23cc0 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
23cd0 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a  constants..**.**
23ce0 20 4e 65 77 20 74 72 61 63 69 6e 67 20 63 6f 6e   New tracing con
23cf0 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 61 64  stants may be ad
23d00 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
23d10 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  leases..**.** ^A
23d20 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
23d30 68 61 73 20 66 6f 75 72 20 61 72 67 75 6d 65 6e  has four argumen
23d40 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c  ts: xCallback(T,
23d50 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20  C,P,X)..** ^The 
23d60 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  T argument is on
23d70 65 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  e of the integer
23d80 20 74 79 70 65 20 63 6f 64 65 73 20 61 62 6f 76   type codes abov
23d90 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67  e..** ^The C arg
23da0 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20  ument is a copy 
23db0 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70  of the context p
23dc0 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e  ointer passed in
23dd0 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   as the.** fourt
23de0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
23df0 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
23e00 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64  )]..** The P and
23e10 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65   X arguments are
23e20 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20   pointers whose 
23e30 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20  meanings depend 
23e40 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  on T..**.** <dl>
23e50 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41  .** [[SQLITE_TRA
23e60 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51  CE_STMT]] <dt>SQ
23e70 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c  LITE_TRACE_STMT<
23e80 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20  /dt>.** <dd>^An 
23e90 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
23ea0 54 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  T callback is in
23eb0 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 70 72 65  voked when a pre
23ec0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
23ed0 2a 2a 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  ** first begins 
23ee0 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73  running and poss
23ef0 69 62 6c 79 20 61 74 20 6f 74 68 65 72 20 74 69  ibly at other ti
23f00 6d 65 73 20 64 75 72 69 6e 67 20 74 68 65 0a 2a  mes during the.*
23f10 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  * execution of t
23f20 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
23f30 65 6d 65 6e 74 2c 20 73 75 63 68 20 61 73 20 61  ement, such as a
23f40 74 20 74 68 65 20 73 74 61 72 74 20 6f 66 20 65  t the start of e
23f50 61 63 68 0a 2a 2a 20 74 72 69 67 67 65 72 20 73  ach.** trigger s
23f60 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20  ubprogram. ^The 
23f70 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
23f80 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
23f90 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
23fa0 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61  ement]. ^The X a
23fb0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
23fc0 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
23fd0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
23fe0 20 75 6e 65 78 70 61 6e 64 65 64 20 53 51 4c 20   unexpanded SQL 
23ff0 74 65 78 74 20 6f 66 20 74 68 65 20 70 72 65 70  text of the prep
24000 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
24010 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  r an SQL comment
24020 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
24030 74 65 73 20 74 68 65 20 69 6e 76 6f 63 61 74 69  tes the invocati
24040 6f 6e 20 6f 66 20 61 20 74 72 69 67 67 65 72 2e  on of a trigger.
24050 20 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20    ^The callback 
24060 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74  can compute.** t
24070 68 65 20 73 61 6d 65 20 74 65 78 74 20 74 68 61  he same text tha
24080 74 20 77 6f 75 6c 64 20 68 61 76 65 20 62 65 65  t would have bee
24090 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
240a0 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
240b0 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e  3_trace()].** in
240c0 74 65 72 66 61 63 65 20 62 79 20 75 73 69 6e 67  terface by using
240d0 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20   the X argument 
240e0 77 68 65 6e 20 58 20 62 65 67 69 6e 73 20 77 69  when X begins wi
240f0 74 68 20 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f  th "--" and invo
24100 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  king.** [sqlite3
24110 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29  _expanded_sql(P)
24120 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  ] otherwise..**.
24130 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43  ** [[SQLITE_TRAC
24140 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e  E_PROFILE]] <dt>
24150 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f  SQLITE_TRACE_PRO
24160 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FILE</dt>.** <dd
24170 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43  >^An SQLITE_TRAC
24180 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61  E_PROFILE callba
24190 63 6b 20 70 72 6f 76 69 64 65 73 20 61 70 70 72  ck provides appr
241a0 6f 78 69 6d 61 74 65 6c 79 20 74 68 65 20 73 61  oximately the sa
241b0 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  me.** informatio
241c0 6e 20 61 73 20 69 73 20 70 72 6f 76 69 64 65 64  n as is provided
241d0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
241e0 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c  _profile()] call
241f0 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20  back..** ^The P 
24200 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
24210 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72  inter to the [pr
24220 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24230 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61  ] and the.** X a
24240 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
24250 6f 20 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67  o a 64-bit integ
24260 65 72 20 77 68 69 63 68 20 69 73 20 74 68 65 20  er which is the 
24270 65 73 74 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20  estimated of.** 
24280 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61  the number of na
24290 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74 20 74 68  nosecond that th
242a0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
242b0 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
242c0 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45  ..** ^The SQLITE
242d0 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63  _TRACE_PROFILE c
242e0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
242f0 65 64 20 77 68 65 6e 20 74 68 65 20 73 74 61 74  ed when the stat
24300 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a  ement finishes..
24310 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  **.** [[SQLITE_T
24320 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53  RACE_ROW]] <dt>S
24330 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c  QLITE_TRACE_ROW<
24340 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20  /dt>.** <dd>^An 
24350 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57  SQLITE_TRACE_ROW
24360 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
24370 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
24380 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
24390 65 6d 65 6e 74 20 67 65 6e 65 72 61 74 65 73 20  ement generates 
243a0 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
243b0 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68  result.  .** ^Th
243c0 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
243d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
243e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
243f0 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a  ment] and the.**
24400 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75   X argument is u
24410 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  nused..**.** [[S
24420 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
24430 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54  E]] <dt>SQLITE_T
24440 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a  RACE_CLOSE</dt>.
24450 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54  ** <dd>^An SQLIT
24460 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 63 61  E_TRACE_CLOSE ca
24470 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
24480 64 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  d when a databas
24490 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
244a0 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20  closes..** ^The 
244b0 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
244c0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
244d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
244e0 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  ion] object.** a
244f0 6e 64 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e  nd the X argumen
24500 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20  t is unused..** 
24510 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
24520 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54   SQLITE_TRACE_ST
24530 4d 54 20 20 20 20 20 20 20 30 78 30 31 0a 23 64  MT       0x01.#d
24540 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
24550 43 45 5f 50 52 4f 46 49 4c 45 20 20 20 20 30 78  CE_PROFILE    0x
24560 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
24570 45 5f 54 52 41 43 45 5f 52 4f 57 20 20 20 20 20  E_TRACE_ROW     
24580 20 20 20 30 78 30 34 0a 23 64 65 66 69 6e 65 20     0x04.#define 
24590 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f  SQLITE_TRACE_CLO
245a0 53 45 20 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a  SE      0x08../*
245b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
245c0 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20  L Trace Hook.** 
245d0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
245e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
245f0 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c  e3_trace_v2(D,M,
24600 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  X,P) interface r
24610 65 67 69 73 74 65 72 73 20 61 20 74 72 61 63 65  egisters a trace
24620 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
24630 63 74 69 6f 6e 20 58 20 61 67 61 69 6e 73 74 20  ction X against 
24640 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
24650 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70  tion] D, using p
24660 72 6f 70 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a  roperty mask M.*
24670 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f  * and context po
24680 69 6e 74 65 72 20 50 2e 20 20 5e 49 66 20 74 68  inter P.  ^If th
24690 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a  e X callback is.
246a0 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68  ** NULL or if th
246b0 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f  e M mask is zero
246c0 2c 20 74 68 65 6e 20 74 72 61 63 69 6e 67 20 69  , then tracing i
246d0 73 20 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65  s disabled.  The
246e0 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e 74 20 73  .** M argument s
246f0 68 6f 75 6c 64 20 62 65 20 74 68 65 20 62 69 74  hould be the bit
24700 77 69 73 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69  wise OR-ed combi
24710 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72  nation of.** zer
24720 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54  o or more [SQLIT
24730 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e  E_TRACE] constan
24740 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  ts..**.** ^Each 
24750 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 73  call to either s
24760 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f  qlite3_trace() o
24770 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f  r sqlite3_trace_
24780 76 32 28 29 20 6f 76 65 72 72 69 64 65 73 20 0a  v2() overrides .
24790 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20 61 6e 79  ** (cancels) any
247a0 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20   prior calls to 
247b0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
247c0 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  or sqlite3_trace
247d0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  _v2()..**.** ^Th
247e0 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e X callback is 
247f0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
24800 20 61 6e 79 20 6f 66 20 74 68 65 20 65 76 65 6e   any of the even
24810 74 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  ts identified by
24820 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75   .** mask M occu
24830 72 2e 20 20 5e 54 68 65 20 69 6e 74 65 67 65 72  r.  ^The integer
24840 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
24850 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  om the callback 
24860 69 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20  is currently.** 
24870 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67 68 20  ignored, though 
24880 74 68 69 73 20 6d 61 79 20 63 68 61 6e 67 65 20  this may change 
24890 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
248a0 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a  es.  Callback.**
248b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
248c0 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a   should return z
248d0 65 72 6f 20 74 6f 20 65 6e 73 75 72 65 20 66 75  ero to ensure fu
248e0 74 75 72 65 20 63 6f 6d 70 61 74 69 62 69 6c 69  ture compatibili
248f0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61  ty..**.** ^A tra
24900 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  ce callback is i
24910 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 6f 75 72  nvoked with four
24920 20 61 72 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c   arguments: call
24930 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a  back(T,C,P,X)..*
24940 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e  * ^The T argumen
24950 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  t is one of the 
24960 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a  [SQLITE_TRACE].*
24970 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69  * constants to i
24980 6e 64 69 63 61 74 65 20 77 68 79 20 74 68 65 20  ndicate why the 
24990 63 61 6c 6c 62 61 63 6b 20 77 61 73 20 69 6e 76  callback was inv
249a0 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20  oked..** ^The C 
249b0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f  argument is a co
249c0 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78  py of the contex
249d0 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68  t pointer..** Th
249e0 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65  e P and X argume
249f0 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73  nts are pointers
24a00 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20   whose meanings 
24a10 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a  depend on T..**.
24a20 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74  ** The sqlite3_t
24a30 72 61 63 65 5f 76 32 28 29 20 69 6e 74 65 72 66  race_v2() interf
24a40 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20  ace is intended 
24a50 74 6f 20 72 65 70 6c 61 63 65 20 74 68 65 20 6c  to replace the l
24a60 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
24a70 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 74 72 61  ces [sqlite3_tra
24a80 63 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ce()] and [sqlit
24a90 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62  e3_profile()], b
24aa0 6f 74 68 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20  oth of which.** 
24ab0 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 0a  are deprecated..
24ac0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
24ad0 72 61 63 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  race_v2(.  sqlit
24ae0 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20  e3*,.  unsigned 
24af0 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43  uMask,.  int(*xC
24b00 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e 65  allback)(unsigne
24b10 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f  d,void*,void*,vo
24b20 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43  id*),.  void *pC
24b30 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tx.);../*.** CAP
24b40 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
24b50 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a  gress Callbacks.
24b60 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
24b70 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
24b80 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
24b90 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20  andler(D,N,X,P) 
24ba0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
24bb0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
24bc0 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62   function X to b
24bd0 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  e invoked period
24be0 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
24bf0 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ng running calls
24c00 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
24c10 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
24c20 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73  3_step()] and [s
24c30 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
24c40 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62  ()] for.** datab
24c50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
24c60 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
24c70 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
24c80 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
24c90 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
24ca0 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
24cb0 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  query..**.** ^Th
24cc0 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  e parameter P is
24cd0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
24ce0 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
24cf0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a  meter to the .**
24d00 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
24d10 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61  on X.  ^The para
24d20 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 61  meter N is the a
24d30 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65  pproximate numbe
24d40 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61  r of .** [virtua
24d50 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75  l machine instru
24d60 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65  ctions] that are
24d70 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65   evaluated betwe
24d80 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a  en successive.**
24d90 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
24da0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20  the callback X. 
24db0 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74   ^If N is less t
24dc0 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65  han one then the
24dd0 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e   progress.** han
24de0 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  dler is disabled
24df0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20  ..**.** ^Only a 
24e00 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20  single progress 
24e10 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64  handler may be d
24e20 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69  efined at one ti
24e30 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62  me per.** [datab
24e40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b  ase connection];
24e50 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70   setting a new p
24e60 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
24e70 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f  cancels the.** o
24e80 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e  ld one.  ^Settin
24e90 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f  g parameter X to
24ea0 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74   NULL disables t
24eb0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
24ec0 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f  ler..** ^The pro
24ed0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73  gress handler is
24ee0 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62   also disabled b
24ef0 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61  y setting N to a
24f00 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74   value less.** t
24f10 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  han 1..**.** ^If
24f20 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
24f30 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
24f40 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65  on-zero, the ope
24f50 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74  ration is.** int
24f60 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20  errupted.  This 
24f70 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75  feature can be u
24f80 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
24f90 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62   a.** "Cancel" b
24fa0 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70  utton on a GUI p
24fb0 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62  rogress dialog b
24fc0 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ox..**.** The pr
24fd0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
24fe0 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
24ff0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
25000 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
25010 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
25020 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
25030 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65  voked the progre
25040 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e  ss handler..** N
25050 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
25060 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
25070 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
25080 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
25090 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
250a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
250b0 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
250c0 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
250d0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
250e0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
250f0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
25100 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c  r(sqlite3*, int,
25110 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
25120 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
25130 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67  API3REF: Opening
25140 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20   A New Database 
25150 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f  Connection.** CO
25160 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  NSTRUCTOR: sqlit
25170 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e3.**.** ^These 
25180 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
25190 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
251a0 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69   file as specifi
251b0 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69  ed by the .** fi
251c0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
251d0 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61   ^The filename a
251e0 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72  rgument is inter
251f0 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20  preted as UTF-8 
25200 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
25210 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
25220 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20  3_open_v2() and 
25230 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
25240 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20   native byte.** 
25250 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
25260 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20  3_open16(). ^(A 
25270 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
25280 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20  tion] handle is 
25290 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72  usually.** retur
252a0 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76  ned in *ppDb, ev
252b0 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  en if an error o
252c0 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79  ccurs.  The only
252d0 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68   exception is th
252e0 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  at.** if SQLite 
252f0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
25300 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
25310 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65  hold the [sqlite
25320 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20  3] object,.** a 
25330 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69  NULL will be wri
25340 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20  tten into *ppDb 
25350 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69  instead of a poi
25360 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
25370 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e  ite3].** object.
25380 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61  )^ ^(If the data
25390 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28  base is opened (
253a0 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20  and/or created) 
253b0 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68  successfully, th
253c0 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  en.** [SQLITE_OK
253d0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
253e0 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  Otherwise an [er
253f0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
25400 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a  urned.)^ ^The.**
25410 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
25420 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
25430 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74  errmsg16()] rout
25440 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  ines can be used
25450 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e   to obtain.** an
25460 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67   English languag
25470 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66  e description of
25480 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f   the error follo
25490 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f  wing a failure o
254a0 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20  f any.** of the 
254b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72  sqlite3_open() r
254c0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
254d0 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
254e0 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46  ding will be UTF
254f0 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73 65 73  -8 for databases
25500 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a   created using.*
25510 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
25520 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
25530 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66  _v2().  ^The def
25540 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  ault encoding fo
25550 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63  r databases.** c
25560 72 65 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c  reated using sql
25570 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69  ite3_open16() wi
25580 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20  ll be UTF-16 in 
25590 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
255a0 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  order..**.** Whe
255b0 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
255c0 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
255d0 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
255e0 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f  esources.** asso
255f0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
25600 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
25610 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f  tion] handle sho
25620 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
25630 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74  by.** passing it
25640 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
25650 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
25660 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
25670 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
25680 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
25690 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
256a0 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70   like sqlite3_op
256b0 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  en().** except t
256c0 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74  hat it accepts t
256d0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
256e0 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
256f0 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a  itional control.
25700 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20  ** over the new 
25710 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25720 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67  ion.  ^(The flag
25730 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
25740 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  * sqlite3_open_v
25750 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  2() can take one
25760 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
25770 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
25780 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
25790 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
257a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
257b0 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  _NOMUTEX], [SQLI
257c0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
257d0 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
257e0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a  _SHAREDCACHE],.*
257f0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
25800 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e  RIVATECACHE], an
25810 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  d/or [SQLITE_OPE
25820 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a  N_URI] flags:)^.
25830 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28  **.** <dl>.** ^(
25840 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
25850 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a  _READONLY]</dt>.
25860 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
25870 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e  ase is opened in
25880 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e   read-only mode.
25890 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73    If the databas
258a0 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c  e does not.** al
258b0 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20  ready exist, an 
258c0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
258d0 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
258e0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
258f0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64  EN_READWRITE]</d
25900 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
25910 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
25920 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
25930 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
25940 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
25950 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  .** only if the 
25960 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
25970 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
25980 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
25990 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63    In either.** c
259a0 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
259b0 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
259c0 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ist, otherwise a
259d0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
259e0 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
259f0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
25a00 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
25a10 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
25a20 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
25a30 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
25a40 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
25a50 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
25a60 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
25a70 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  d if.** it does 
25a80 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
25a90 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
25aa0 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
25ab0 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
25ac0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
25ad0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
25ae0 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a  en16().</dd>)^.*
25af0 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </dl>.**.** If
25b00 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
25b10 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
25b20 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f  en_v2() is not o
25b30 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d  ne of the.** com
25b40 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
25b50 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79  above optionally
25b60 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f   combined with o
25b70 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ther.** [SQLITE_
25b80 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  OPEN_READONLY | 
25b90 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69  SQLITE_OPEN_* bi
25ba0 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ts].** then the 
25bb0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
25bc0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  fined..**.** ^If
25bd0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
25be0 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
25bf0 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
25c00 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
25c10 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
25c20 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
25c30 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
25c40 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
25c50 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
25c60 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
25c70 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
25c80 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
25c90 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65  t-time.  ^If the
25ca0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
25cb0 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
25cc0 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
25cd0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
25ce0 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
25cf0 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
25d00 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
25d10 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
25d20 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
25d30 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
25d40 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
25d50 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
25d60 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
25d70 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
25d80 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
25d90 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
25da0 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65  ction to be.** e
25db0 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b  ligible to use [
25dc0 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
25dd0 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  e], regardless o
25de0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
25df0 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
25e00 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   is enabled usin
25e10 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  g [sqlite3_enabl
25e20 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
25e30 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c  ].  ^The.** [SQL
25e40 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
25e50 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
25e60 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
25e70 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f  connection to no
25e80 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65  t.** participate
25e90 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68   in [shared cach
25ea0 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20  e mode] even if 
25eb0 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  it is enabled..*
25ec0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
25ed0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
25ee0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
25ef0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
25f00 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
25f10 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  fs] object that 
25f20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72  defines the oper
25f30 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
25f40 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74  erface that.** t
25f50 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
25f60 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
25f70 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20  d use.  ^If the 
25f80 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
25f90 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f   is.** a NULL po
25fa0 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64  inter then the d
25fb0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
25fc0 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75  vfs] object is u
25fd0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  sed..**.** ^If t
25fe0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22  he filename is "
25ff0 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
26000 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
26010 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  rary in-memory d
26020 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72  atabase.** is cr
26030 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
26040 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73  nnection.  ^This
26050 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
26060 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
26070 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  when.** the data
26080 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
26090 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
260a0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
260b0 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d  QLite might.** m
260c0 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
260d0 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
260e0 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67  lenames that beg
260f0 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
26100 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74  character..** It
26110 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
26120 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61  that when a data
26130 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63  base filename ac
26140 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  tually does begi
26150 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20  n with.** a ":" 
26160 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68  character you sh
26170 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20  ould prefix the 
26180 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
26190 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73  pathname such as
261a0 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69  .** "./" to avoi
261b0 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
261c0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
261d0 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
261e0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
261f0 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
26200 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
26210 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
26220 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72  eated.  ^This pr
26230 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77  ivate database w
26240 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61  ill be.** automa
26250 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
26260 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64  as soon as the d
26270 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26280 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
26290 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
262a0 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f  mes in sqlite3_o
262b0 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20  pen()]] <h3>URI 
262c0 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a  Filenames</h3>.*
262d0 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69  *.** ^If [URI fi
262e0 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65  lename] interpre
262f0 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
26300 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e  d, and the filen
26310 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
26320 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c  begins with "fil
26330 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69  e:", then the fi
26340 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70  lename is interp
26350 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20  reted as a URI. 
26360 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ^URI.** filename
26370 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
26380 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
26390 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
263a0 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73  RI] flag is.** s
263b0 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68  et in the fourth
263c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
263d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20  ite3_open_v2(), 
263e0 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  or if it has.** 
263f0 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f  been enabled glo
26400 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20  bally using the 
26410 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
26420 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20  RI] option with 
26430 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
26440 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64  config()] method
26450 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49   or by the [SQLI
26460 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70  TE_USE_URI] comp
26470 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
26480 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65  .** As of SQLite
26490 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20   version 3.7.7, 
264a0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  URI filename int
264b0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74  erpretation is t
264c0 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20  urned off.** by 
264d0 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74  default, but fut
264e0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
264f0 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61  SQLite might ena
26500 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  ble URI filename
26510 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69  .** interpretati
26520 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  on by default.  
26530 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61  See "[URI filena
26540 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69  mes]" for additi
26550 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
26560 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66  ion..**.** URI f
26570 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72  ilenames are par
26580 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  sed according to
26590 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74   RFC 3986. ^If t
265a0 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20  he URI contains 
265b0 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c  an.** authority,
265c0 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65   then it must be
265d0 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79   either an empty
265e0 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73   string or the s
265f0 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c  tring .** "local
26600 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61  host". ^If the a
26610 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20  uthority is not 
26620 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
26630 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20  or "localhost", 
26640 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20  an .** error is 
26650 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20  returned to the 
26660 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61  caller. ^The fra
26670 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  gment component 
26680 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a  of a URI, if .**
26690 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e   present, is ign
266a0 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ored..**.** ^SQL
266b0 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74  ite uses the pat
266c0 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74  h component of t
266d0 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61  he URI as the na
266e0 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66  me of the disk f
266f0 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e  ile.** which con
26700 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61  tains the databa
26710 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  se. ^If the path
26720 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27   begins with a '
26730 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a  /' character, .*
26740 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74  * then it is int
26750 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61  erpreted as an a
26760 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49  bsolute path. ^I
26770 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20  f the path does 
26780 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69  not begin .** wi
26790 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e  th a '/' (meanin
267a0 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  g that the autho
267b0 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20  rity section is 
267c0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
267d0 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68   URI).** then th
267e0 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70  e path is interp
267f0 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74  reted as a relat
26800 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28  ive path. .** ^(
26810 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20  On windows, the 
26820 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  first component 
26830 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  of an absolute p
26840 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69  ath .** is a dri
26850 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e  ve specification
26860 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a   (e.g. "C:").)^.
26870 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49  **.** [[core URI
26880 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
26890 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79  s]].** The query
268a0 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
268b0 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  URI may contain 
268c0 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
268d0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a  are interpreted.
268e0 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c  ** either by SQL
268f0 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62  ite itself, or b
26900 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f  y a [VFS | custo
26910 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  m VFS implementa
26920 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65  tion]..** SQLite
26930 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69   and its built-i
26940 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70  n [VFSes] interp
26950 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ret the.** follo
26960 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d  wing query param
26970 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  eters:.**.** <ul
26980 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76  >.**   <li> <b>v
26990 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66  fs</b>: ^The "vf
269a0 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  s" parameter may
269b0 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63   be used to spec
269c0 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a  ify the name of.
269d0 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a  **     a VFS obj
269e0 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65  ect that provide
269f0 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
26a00 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
26a10 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20   that should.** 
26a20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61      be used to a
26a30 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
26a40 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e  se file on disk.
26a50 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e   ^If this option
26a60 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20   is set to.**   
26a70 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e    an empty strin
26a80 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  g the default VF
26a90 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  S object is used
26aa0 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  . ^Specifying an
26ab0 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20   unknown.**     
26ac0 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e  VFS is an error.
26ad0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
26ae0 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
26af0 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f  nd the vfs optio
26b00 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73  n is.**     pres
26b10 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46  ent, then the VF
26b20 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  S specified by t
26b30 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  he option takes 
26b40 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a  precedence over.
26b50 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65  **     the value
26b60 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
26b70 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
26b80 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
26b90 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
26ba0 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20  i> <b>mode</b>: 
26bb0 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d  ^(The mode param
26bc0 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
26bd0 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20  to either "ro", 
26be0 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77  "rw",.**     "rw
26bf0 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e  c", or "memory".
26c00 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73   Attempting to s
26c10 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68  et it to any oth
26c20 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20  er value is.**  
26c30 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a     an error)^. .
26c40 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20  **     ^If "ro" 
26c50 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68  is specified, th
26c60 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
26c70 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
26c80 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20  ad-only .**     
26c90 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20  access, just as 
26ca0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
26cb0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c  PEN_READONLY] fl
26cc0 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20  ag had been set 
26cd0 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74  in the .**     t
26ce0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
26cf0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
26d00 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  (). ^If the mode
26d10 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
26d20 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20  o .**     "rw", 
26d30 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
26d40 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
26d50 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20  read-write (but 
26d60 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20  not create) .** 
26d70 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69      access, as i
26d80 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  f SQLITE_OPEN_RE
26d90 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74  ADWRITE (but not
26da0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
26db0 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20  ATE) had .**    
26dc0 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75   been set. ^Valu
26dd0 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76  e "rwc" is equiv
26de0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
26df0 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51   both .**     SQ
26e00 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
26e10 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f  ITE and SQLITE_O
26e20 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66  PEN_CREATE.  ^If
26e30 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
26e40 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74   is.**     set t
26e50 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20  o "memory" then 
26e60 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72  a pure [in-memor
26e70 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74  y database] that
26e80 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20   never reads.** 
26e90 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72      or writes fr
26ea0 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e  om disk is used.
26eb0 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72   ^It is an error
26ec0 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61   to specify a va
26ed0 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74  lue for.**     t
26ee0 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
26ef0 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72  r that is less r
26f00 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20  estrictive than 
26f10 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62  that specified b
26f20 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61  y.**     the fla
26f30 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65  gs passed in the
26f40 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
26f50 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
26f60 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
26f70 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e  li> <b>cache</b>
26f80 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72  : ^The cache par
26f90 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
26fa0 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61  t to either "sha
26fb0 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22  red" or.**     "
26fc0 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69  private". ^Setti
26fd0 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64  ng it to "shared
26fe0 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
26ff0 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a  to setting the.*
27000 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
27010 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69  N_SHAREDCACHE bi
27020 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61  t in the flags a
27030 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74  rgument passed t
27040 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33  o.**     sqlite3
27050 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74  _open_v2(). ^Set
27060 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70  ting the cache p
27070 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69  arameter to "pri
27080 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20  vate" is .**    
27090 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
270a0 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54  etting the SQLIT
270b0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
270c0 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20  CHE bit..**     
270d0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
270e0 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
270f0 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61  d the "cache" pa
27100 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65  rameter is prese
27110 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55  nt in.**     a U
27120 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73  RI filename, its
27130 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73   value overrides
27140 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65   any behavior re
27150 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69  quested by setti
27160 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ng.**     SQLITE
27170 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
27180 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45  HE or SQLITE_OPE
27190 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c  N_SHAREDCACHE fl
271a0 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  ag..**.**  <li> 
271b0 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68  <b>psow</b>: ^Th
271c0 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72  e psow parameter
271d0 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74 68   indicates wheth
271e0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a  er or not the.**
271f0 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20       [powersafe 
27200 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65  overwrite] prope
27210 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73  rty does or does
27220 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68   not apply to th
27230 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65  e.**     storage
27240 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20   media on which 
27250 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
27260 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a  e resides..**.**
27270 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b    <li> <b>nolock
27280 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63  </b>: ^The noloc
27290 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  k parameter is a
272a0 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70   boolean query p
272b0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20  arameter.**     
272c0 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73  which if set dis
272d0 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69  ables file locki
272e0 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a  ng in rollback j
272f0 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54  ournal modes.  T
27300 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73  his.**     is us
27310 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69  eful for accessi
27320 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e  ng a database on
27330 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68   a filesystem th
27340 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20  at does not.**  
27350 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69     support locki
27360 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44  ng.  Caution:  D
27370 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
27380 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  on might result 
27390 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72  if two.**     or
273a0 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20   more processes 
273b0 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d  write to the sam
273c0 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  e database and a
273d0 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a  ny one of those.
273e0 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73  **     processes
273f0 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a   uses nolock=1..
27400 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69  **.**  <li> <b>i
27410 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54  mmutable</b>: ^T
27420 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72  he immutable par
27430 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c  ameter is a bool
27440 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20  ean query.**    
27450 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
27460 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
27470 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
27480 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a   is stored on.**
27490 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d       read-only m
274a0 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d  edia.  ^When imm
274b0 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53  utable is set, S
274c0 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
274d0 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61  at the.**     da
274e0 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e  tabase file cann
274f0 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65  ot be changed, e
27500 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73  ven by a process
27510 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20   with higher.** 
27520 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61      privilege, a
27530 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61  nd so the databa
27540 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61  se is opened rea
27550 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c  d-only and all l
27560 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e  ocking.**     an
27570 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69  d change detecti
27580 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20  on is disabled. 
27590 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e   Caution: Settin
275a0 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a  g the immutable.
275b0 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20  **     property 
275c0 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  on a database fi
275d0 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20  le that does in 
275e0 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20  fact change can 
275f0 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e  result.**     in
27600 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79   incorrect query
27610 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20   results and/or 
27620 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
27630 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20   errors..**     
27640 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
27650 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
27660 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a  E]..**       .**
27670 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70   </ul>.**.** ^Sp
27680 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
27690 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e  own parameter in
276a0 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   the query compo
276b0 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73  nent of a URI is
276c0 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72   not an.** error
276d0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
276e0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
276f0 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64  ht understand ad
27700 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a  ditional query.*
27710 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53  * parameters.  S
27720 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d  ee "[query param
27730 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69  eters with speci
27740 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51  al meaning to SQ
27750 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64  Lite]" for.** ad
27760 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
27770 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  tion..**.** [[UR
27780 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
27790 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69  les]] <h3>URI fi
277a0 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c  lename examples<
277b0 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c  /h3>.**.** <tabl
277c0 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69  e border="1" ali
277d0 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61  gn=center cellpa
277e0 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e  dding=5>.** <tr>
277f0 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d  <th> URI filenam
27800 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a  es <th> Results.
27810 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
27820 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  :data.db <td> .*
27830 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
27840 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
27850 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
27860 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20  t directory..** 
27870 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
27880 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
27890 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <br>.**         
278a0 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72   file:///home/fr
278b0 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
278c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
278d0 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f  e://localhost/ho
278e0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
278f0 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  <br> <td> .**   
27900 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
27910 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f  database file "/
27920 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
27930 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  b"..** <tr><td> 
27940 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f  file://darkstar/
27950 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
27960 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
27970 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64      An error. "d
27980 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20  arkstar" is not 
27990 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74  a recognized aut
279a0 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  hority..** <tr><
279b0 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d  td style="white-
279c0 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a  space:nowrap"> .
279d0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
279e0 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73  :///C:/Documents
279f0 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67  %20and%20Setting
27a00 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64  s/fred/Desktop/d
27a10 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74  ata.db.**     <t
27a20 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a  d> Windows only:
27a30 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
27a40 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64  data.db" on fred
27a50 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72  's desktop on dr
27a60 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
27a70 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  C:. Note that th
27a80 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69  e %20 escaping i
27a90 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69  n this example i
27aa0 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a  s not strictly .
27ab0 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65  **          nece
27ac0 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68  ssary - space ch
27ad0 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20  aracters can be 
27ae0 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a  used literally.*
27af0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52  *          in UR
27b00 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20  I filenames..** 
27b10 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
27b20 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61  ta.db?mode=ro&ca
27b30 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e  che=private <td>
27b40 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
27b50 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  en file "data.db
27b60 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
27b70 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72   directory for r
27b80 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e  ead-only access.
27b90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67  .**          Reg
27ba0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
27bb0 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
27bc0 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65  -cache mode is e
27bd0 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20  nabled by.**    
27be0 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75        default, u
27bf0 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63  se a private cac
27c00 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  he..** <tr><td> 
27c10 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
27c20 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78  data.db?vfs=unix
27c30 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a  -dotfile <td>.**
27c40 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
27c50 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
27c60 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68  data.db". Use th
27c70 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75  e special VFS "u
27c80 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20  nix-dotfile".** 
27c90 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73           that us
27ca0 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20  es dot-files in 
27cb0 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61  place of posix a
27cc0 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e  dvisory locking.
27cd0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
27ce0 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
27cf0 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a  eadonly <td> .**
27d00 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
27d10 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69  or. "readonly" i
27d20 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70  s not a valid op
27d30 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f  tion for the "mo
27d40 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  de" parameter..*
27d50 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a  * </table>.**.**
27d60 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61   ^URI hexadecima
27d70 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
27d80 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70  es (%HH) are sup
27d90 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68  ported within th
27da0 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75  e path and.** qu
27db0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
27dc0 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64  f a URI. A hexad
27dd0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
27de0 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20  quence consists 
27df0 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20  of a.** percent 
27e00 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c  sign - "%" - fol
27e10 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79  lowed by exactly
27e20 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c   two hexadecimal
27e30 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63   digits .** spec
27e40 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20  ifying an octet 
27e50 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74  value. ^Before t
27e60 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79  he path or query
27e70 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
27e80 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
27e90 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
27ea0 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64  , they are encod
27eb0 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61  ed using UTF-8 a
27ec0 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64  nd all .** hexad
27ed0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
27ee0 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64  quences replaced
27ef0 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74   by a single byt
27f00 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
27f10 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  .** correspondin
27f20 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73  g octet. If this
27f30 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74   process generat
27f40 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54  es an invalid UT
27f50 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a  F-8 encoding,.**
27f60 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
27f70 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
27f80 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
27f90 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
27fa0 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
27fb0 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
27fc0 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
27fd0 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
27fe0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
27ff0 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20  en_v2() must be 
28000 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
28010 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
28020 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
28030 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
28040 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
28050 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
28060 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
28070 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
28080 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
28090 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
280a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
280b0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
280c0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  v2()..**.** <b>N
280d0 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
280e0 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
280f0 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
28100 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
28110 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
28120 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  to calling sqlit
28130 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
28140 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
28150 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
28160 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
28170 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
28180 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
28190 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
281a0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
281b0 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  : [sqlite3_temp_
281c0 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e  directory].*/.in
281d0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
281e0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
281f0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
28200 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
28210 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
28220 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
28230 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
28240 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
28250 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
28260 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
28270 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
28280 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
28290 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
282a0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
282b0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
282c0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
282d0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
282e0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
282f0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
28300 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
28310 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
28320 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
28330 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
28340 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
28350 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
28360 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
28370 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
28380 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
28390 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
283a0 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
283b0 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
283c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
283d0 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65  EF: Obtain Value
283e0 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65  s For URI Parame
283f0 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ters.**.** These
28400 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75   are utility rou
28410 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f  tines, useful to
28420 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
28430 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b  ions, that check
28440 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20  .** to see if a 
28450 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
28460 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e  s a URI that con
28470 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69  tained a specifi
28480 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61  c query .** para
28490 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f  meter, and if so
284a0 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c   obtains the val
284b0 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79  ue of that query
284c0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
284d0 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61  * If F is the da
284e0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
284f0 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69  pointer passed i
28500 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20  nto the xOpen() 
28510 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20  method of .** a 
28520 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
28530 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67  on when the flag
28540 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  s parameter to x
28550 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f  Open() has one o
28560 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68  r .** more of th
28570 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
28580 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  RI] or [SQLITE_O
28590 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74  PEN_MAIN_DB] bit
285a0 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69  s set and.** P i
285b0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
285c0 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
285d0 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  r, then.** sqlit
285e0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
285f0 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68  (F,P) returns th
28600 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50  e value of the P
28610 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66  .** parameter if
28620 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20   it exists or a 
28630 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
28640 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61  P does not appea
28650 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79  r as a .** query
28660 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e   parameter on F.
28670 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72    If P is a quer
28680 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46  y parameter of F
28690 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69  .** has no expli
286a0 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  cit value, then 
286b0 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
286c0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
286d0 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ns.** a pointer 
286e0 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
286f0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ng..**.** The sq
28700 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
28710 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
28720 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20   assumes that P 
28730 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20  is a boolean.** 
28740 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
28750 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f  turns true (1) o
28760 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f  r false (0) acco
28770 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c  rding to the val
28780 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65  ue.** of P.  The
28790 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
287a0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
287b0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ine returns true
287c0 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76   (1) if the.** v
287d0 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61  alue of query pa
287e0 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
287f0 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65   of "yes", "true
28800 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e  ", or "on" in an
28810 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20  y.** case or if 
28820 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
28830 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f   with a non-zero
28840 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a   number.  The .*
28850 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
28860 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
28870 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61  tines returns fa
28880 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76  lse (0) if the v
28890 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79  alue of.** query
288a0 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
288b0 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61  one of "no", "fa
288c0 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69  lse", or "off" i
288d0 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a  n any case or.**
288e0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
288f0 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65  gins with a nume
28900 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20  ric zero.  If P 
28910 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a  is not a query.*
28920 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  * parameter on F
28930 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
28940 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f   of P is does no
28950 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74  t match any of t
28960 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65  he.** above, the
28970 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  n sqlite3_uri_bo
28980 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
28990 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a  urns (B!=0)..**.
289a0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
289b0 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20  ri_int64(F,P,D) 
289c0 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73  routine converts
289d0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
289e0 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74  into a.** 64-bit
289f0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
28a00 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74  and returns that
28a10 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69   integer, or D i
28a20 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  f P does not.** 
28a30 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76  exist.  If the v
28a40 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d  alue of P is som
28a50 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
28a60 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  n an integer, th
28a70 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65  en.** zero is re
28a80 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49  turned..** .** I
28a90 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f F is a NULL po
28aa0 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69  inter, then sqli
28ab0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
28ac0 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e  r(F,P) returns N
28ad0 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  ULL and.** sqlit
28ae0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
28af0 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e  ,P,B) returns B.
28b00 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20    If F is not a 
28b10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
28b20 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74  .** is not a dat
28b30 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e  abase file pathn
28b40 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ame pointer that
28b50 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69   SQLite passed i
28b60 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a  nto the xOpen.**
28b70 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65   VFS method, the
28b80 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
28b90 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  f this routine i
28ba0 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
28bb0 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65  probably.** unde
28bc0 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73  sirable..*/.cons
28bd0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
28be0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
28bf0 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
28c00 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
28c10 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71  *zParam);.int sq
28c20 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
28c30 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  n(const char *zF
28c40 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ile, const char 
28c50 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65  *zParam, int bDe
28c60 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f  fault);.sqlite3_
28c70 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72  int64 sqlite3_ur
28c80 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68  i_int64(const ch
28c90 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  ar*, const char*
28ca0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
28cb0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
28cc0 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
28cd0 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20  And Messages.** 
28ce0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
28cf0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
28d00 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65  st recent sqlite
28d10 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73  3_* API call ass
28d20 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a  ociated with .**
28d30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
28d40 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c  ction] D failed,
28d50 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
28d60 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74  3_errcode(D) int
28d70 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e  erface.** return
28d80 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
28d90 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b  esult code] or [
28da0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
28db0 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a  code] for that.*
28dc0 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49  * API call..** I
28dd0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
28de0 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20 73  t API call was s
28df0 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68  uccessful,.** th
28e00 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
28e10 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
28e20 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e  _errcode() is un
28e30 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  defined..** ^The
28e40 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
28e50 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69  d_errcode().** i
28e60 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20  nterface is the 
28e70 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74  same except that
28e80 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
28e90 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65  ns the .** [exte
28ea0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
28eb0 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65  ] even when exte
28ec0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
28ed0 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
28ee0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
28ef0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61  lite3_errmsg() a
28f00 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  nd sqlite3_errms
28f10 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67  g16() return Eng
28f20 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a  lish-language.**
28f30 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72   text that descr
28f40 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20  ibes the error, 
28f50 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
28f60 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63  or UTF-16 respec
28f70 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d  tively..** ^(Mem
28f80 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
28f90 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
28fa0 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
28fb0 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54  internally..** T
28fc0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
28fd0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
28fe0 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65  worry about free
28ff0 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a  ing the result..
29000 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
29010 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67  error string mig
29020 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ht be overwritte
29030 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
29040 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e   by.** subsequen
29050 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72  t calls to other
29060 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
29070 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a  e functions.)^.*
29080 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
29090 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72  3_errstr() inter
290a0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
290b0 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
290c0 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64  e text.** that d
290d0 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65  escribes the [re
290e0 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55  sult code], as U
290f0 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  TF-8..** ^(Memor
29100 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
29110 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
29120 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
29130 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20  ternally.** and 
29140 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65  must not be free
29150 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
29160 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68  tion)^..**.** Wh
29170 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
29180 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
29190 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
291a0 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
291b0 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
291c0 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
291d0 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
291e0 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
291f0 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
29200 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
29210 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
29220 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
29230 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
29240 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
29250 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
29260 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
29270 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
29280 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
29290 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
292a0 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
292b0 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
292c0 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
292d0 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
292e0 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
292f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
29300 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
29310 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
29320 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
29330 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
29340 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
29350 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
29360 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
29370 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
29380 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
29390 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
293a0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
293b0 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
293c0 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
293d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
293e0 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
293f0 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
29400 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
29410 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
29420 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
29430 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
29440 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
29450 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
29460 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
29470 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
29480 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
29490 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
294a0 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
294b0 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  db);.int sqlite3
294c0 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
294d0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
294e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
294f0 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
29500 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  e3*);.const void
29510 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
29520 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  16(sqlite3*);.co
29530 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
29540 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a  3_errstr(int);..
29550 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29560 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
29570 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  nt Object.** KEY
29580 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
29590 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
295a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
295b0 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
295c0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
295d0 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
295e0 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
295f0 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61 73  ment that.** has
29600 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69   been compiled i
29610 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d 20  nto binary form 
29620 61 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f 20  and is ready to 
29630 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a  be evaluated..**
29640 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61 63  .** Think of eac
29650 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
29660 61 73 20 61 20 73 65 70 61 72 61 74 65 20 63 6f  as a separate co
29670 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e 20  mputer program. 
29680 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   The.** original
29690 20 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f 75   SQL text is sou
296a0 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72 65  rce code.  A pre
296b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
296c0 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74 68  object .** is th
296d0 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63  e compiled objec
296e0 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c  t code.  All SQL
296f0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
29700 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65  ed into a.** pre
29710 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
29720 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62 65  before it can be
29730 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   run..**.** The 
29740 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61 20  life-cycle of a 
29750 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29760 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c  nt object usuall
29770 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69 73  y goes like this
29780 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
29790 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20  <li> Create the 
297a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
297b0 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  nt object using 
297c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
297d0 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20  _v2()]..** <li> 
297e0 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b  Bind values to [
297f0 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e  parameters] usin
29800 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
29810 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69  nd_*().**      i
29820 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c  nterfaces..** <l
29830 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62  i> Run the SQL b
29840 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
29850 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f  e3_step()] one o
29860 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
29870 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20   <li> Reset the 
29880 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29890 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
298a0 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
298b0 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
298c0 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
298d0 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
298e0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
298f0 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
29900 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
29910 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
29920 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64  * </ol>.*/.typed
29930 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
29940 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
29950 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
29960 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
29970 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  imits.** METHOD:
29980 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
29990 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  (This interface 
299a0 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
299b0 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
299c0 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
299d0 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
299e0 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
299f0 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
29a00 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
29a10 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
29a20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
29a30 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
29a40 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
29a50 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
29a60 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
29a70 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
29a80 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
29a90 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
29aa0 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
29ab0 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
29ac0 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
29ad0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
29ae0 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
29af0 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
29b00 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  ruct.)^.**.** ^I
29b10 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
29b20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
29b30 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
29b40 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
29b50 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69   ^(For each limi
29b60 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54  t category SQLIT
29b70 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c  E_LIMIT_<i>NAME<
29b80 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a  /i> there is a .
29b90 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
29ba0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
29bb0 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  * set at compile
29bc0 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65  -time by a C pre
29bd0 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
29be0 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74  called.** [limit
29bf0 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c  s | SQLITE_MAX_<
29c00 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20  i>NAME</i>]..** 
29c10 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
29c20 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
29c30 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
29c40 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74  .))^.** ^Attempt
29c50 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
29c60 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
29c70 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
29c80 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
29c90 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
29ca0 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
29cb0 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72  nd..**.** ^Regar
29cc0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
29cd0 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69   or not the limi
29ce0 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74  t was changed, t
29cf0 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
29d00 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61  limit()] interfa
29d10 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70  ce returns the p
29d20 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
29d30 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e  e limit..** ^Hen
29d40 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ce, to find the 
29d50 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
29d60 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74   a limit without
29d70 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a   changing it,.**
29d80 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74   simply invoke t
29d90 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69  his interface wi
29da0 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72  th the third par
29db0 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31  ameter set to -1
29dc0 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
29dd0 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
29de0 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
29df0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
29e00 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
29e10 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
29e20 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
29e30 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
29e40 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
29e50 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
29e60 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
29e70 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
29e80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
29e90 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
29ea0 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
29eb0 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
29ec0 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
29ed0 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
29ee0 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
29ef0 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
29f00 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
29f10 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
29f20 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
29f30 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
29f40 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
29f50 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
29f60 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
29f70 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
29f80 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
29f90 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
29fa0 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
29fb0 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
29fc0 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
29fd0 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
29fe0 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
29ff0 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
2a000 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
2a010 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
2a020 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
2a030 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
2a040 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
2a050 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
2a060 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
2a070 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
2a080 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
2a090 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
2a0a0 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
2a0b0 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
2a0c0 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
2a0d0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
2a0e0 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
2a0f0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
2a100 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
2a110 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
2a120 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
2a130 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
2a140 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
2a150 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
2a160 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
2a170 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
2a180 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
2a190 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
2a1a0 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
2a1b0 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
2a1c0 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
2a1d0 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
2a1e0 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
2a1f0 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
2a200 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
2a210 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
2a220 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
2a230 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
2a240 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
2a250 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
2a260 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
2a270 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
2a280 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
2a290 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
2a2a0 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
2a2b0 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
2a2c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2a2d0 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  T_LENGTH]] ^(<dt
2a2e0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
2a2f0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
2a300 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
2a310 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
2a320 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
2a330 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c   row, in bytes.<
2a340 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2a350 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
2a360 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
2a370 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
2a380 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
2a390 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
2a3a0 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
2a3b0 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
2a3c0 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
2a3d0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2a3e0 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53  COLUMN]] ^(<dt>S
2a3f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
2a400 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
2a410 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
2a420 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2a430 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
2a440 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
2a450 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
2a460 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
2a470 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
2a480 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
2a490 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
2a4a0 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
2a4b0 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
2a4c0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2a4d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
2a4e0 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
2a4f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
2a500 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
2a510 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
2a520 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
2a530 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
2a540 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
2a550 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2a560 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
2a570 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LECT]] ^(<dt>SQL
2a580 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
2a590 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
2a5a0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2a5b0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
2a5c0 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
2a5d0 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
2a5e0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2a5f0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  [SQLITE_LIMIT_VD
2a600 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51  BE_OP]] ^(<dt>SQ
2a610 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
2a620 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
2a630 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
2a640 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
2a650 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
2a660 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
2a670 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
2a680 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
2a690 6d 65 6e 74 2e 20 20 49 66 20 5b 73 71 6c 69 74  ment.  If [sqlit
2a6a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2a6b0 20 6f 72 0a 2a 2a 20 74 68 65 20 65 71 75 69 76   or.** the equiv
2a6c0 61 6c 65 6e 74 20 74 72 69 65 73 20 74 6f 20 61  alent tries to a
2a6d0 6c 6c 6f 63 61 74 65 20 73 70 61 63 65 20 66 6f  llocate space fo
2a6e0 72 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 69 73  r more than this
2a6f0 20 6d 61 6e 79 20 6f 70 63 6f 64 65 73 0a 2a 2a   many opcodes.**
2a700 20 69 6e 20 61 20 73 69 6e 67 6c 65 20 70 72 65   in a single pre
2a710 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c  pared statement,
2a720 20 61 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d   an SQLITE_NOMEM
2a730 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
2a740 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
2a750 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2a760 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e  FUNCTION_ARG]] ^
2a770 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2a780 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
2a790 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2a7a0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2a7b0 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
2a7c0 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  function.</dd>)^
2a7d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2a7e0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d  LIMIT_ATTACHED]]
2a7f0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2a800 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74  MIT_ATTACHED</dt
2a810 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2a820 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b  imum number of [
2a830 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65  ATTACH | attache
2a840 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c  d databases].)^<
2a850 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
2a860 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
2a870 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a  ATTERN_LENGTH]].
2a880 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
2a890 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
2a8a0 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
2a8b0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2a8c0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
2a8d0 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
2a8e0 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
2a8f0 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
2a900 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
2a910 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2a920 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
2a930 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ER]].** ^(<dt>SQ
2a940 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
2a950 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
2a960 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2a970 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20  um index number 
2a980 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65  of any [paramete
2a990 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  r] in an SQL sta
2a9a0 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  tement.)^.**.** 
2a9b0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  [[SQLITE_LIMIT_T
2a9c0 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e  RIGGER_DEPTH]] ^
2a9d0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2a9e0 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c  T_TRIGGER_DEPTH<
2a9f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2aa00 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
2aa10 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74   recursion for t
2aa20 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a  riggers.</dd>)^.
2aa30 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2aa40 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
2aa50 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ADS]] ^(<dt>SQLI
2aa60 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
2aa70 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20  THREADS</dt>.** 
2aa80 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2aa90 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69  number of auxili
2aaa0 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61  ary worker threa
2aab0 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65  ds that a single
2aac0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2aad0 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61  atement] may sta
2aae0 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  rt.</dd>)^.** </
2aaf0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
2ab00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2ab10 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
2ab20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
2ab30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
2ab40 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
2ab50 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
2ab60 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
2ab70 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
2ab80 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
2ab90 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
2aba0 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
2abb0 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
2abc0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2abd0 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
2abe0 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
2abf0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2ac00 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
2ac10 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
2ac20 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2ac30 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
2ac40 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
2ac50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2ac60 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
2ac70 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
2ac80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2ac90 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
2aca0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
2acb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2acc0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
2acd0 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
2ace0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2acf0 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
2ad00 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
2ad10 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
2ad20 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
2ad30 52 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20  READS           
2ad40 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  11../*.** CAPI3R
2ad50 45 46 3a 20 50 72 65 70 61 72 65 20 46 6c 61 67  EF: Prepare Flag
2ad60 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
2ad70 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
2ad80 61 72 69 6f 75 73 20 66 6c 61 67 73 20 74 68 61  arious flags tha
2ad90 74 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  t can be passed 
2ada0 69 6e 74 6f 0a 2a 2a 20 22 70 72 65 70 46 6c 61  into.** "prepFla
2adb0 67 73 22 20 70 61 72 61 6d 65 74 65 72 20 6f 66  gs" parameter of
2adc0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
2add0 65 70 61 72 65 5f 76 33 28 29 5d 20 61 6e 64 0a  epare_v3()] and.
2ade0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2adf0 61 72 65 31 36 5f 76 33 28 29 5d 20 69 6e 74 65  are16_v3()] inte
2ae00 72 66 61 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65  rfaces..**.** Ne
2ae10 77 20 66 6c 61 67 73 20 6d 61 79 20 62 65 20 61  w flags may be a
2ae20 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
2ae30 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
2ae40 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  e..**.** <dl>.**
2ae50 20 5b 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52   [[SQLITE_PREPAR
2ae60 45 5f 50 45 52 53 49 53 54 45 4e 54 5d 5d 20 5e  E_PERSISTENT]] ^
2ae70 28 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52 45 50  (<dt>SQLITE_PREP
2ae80 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 3c 2f  ARE_PERSISTENT</
2ae90 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53  dt>.** <dd>The S
2aea0 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45  QLITE_PREPARE_PE
2aeb0 52 53 49 53 54 45 4e 54 20 66 6c 61 67 20 69 73  RSISTENT flag is
2aec0 20 61 20 68 69 6e 74 20 74 6f 20 74 68 65 20 71   a hint to the q
2aed0 75 65 72 79 20 70 6c 61 6e 6e 65 72 0a 2a 2a 20  uery planner.** 
2aee0 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65  that the prepare
2aef0 64 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  d statement will
2af00 20 62 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72   be retained for
2af10 20 61 20 6c 6f 6e 67 20 74 69 6d 65 20 61 6e 64   a long time and
2af20 0a 2a 2a 20 70 72 6f 62 61 62 6c 79 20 72 65 75  .** probably reu
2af30 73 65 64 20 6d 61 6e 79 20 74 69 6d 65 73 2e 29  sed many times.)
2af40 5e 20 5e 57 69 74 68 6f 75 74 20 74 68 69 73 20  ^ ^Without this 
2af50 66 6c 61 67 2c 20 5b 73 71 6c 69 74 65 33 5f 70  flag, [sqlite3_p
2af60 72 65 70 61 72 65 5f 76 33 28 29 5d 0a 2a 2a 20  repare_v3()].** 
2af70 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2af80 70 61 72 65 31 36 5f 76 33 28 29 5d 20 61 73 73  pare16_v3()] ass
2af90 75 6d 65 20 74 68 61 74 20 74 68 65 20 70 72 65  ume that the pre
2afa0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2afb0 77 69 6c 6c 20 0a 2a 2a 20 62 65 20 75 73 65 64  will .** be used
2afc0 20 6a 75 73 74 20 6f 6e 63 65 20 6f 72 20 61 74   just once or at
2afd0 20 6d 6f 73 74 20 61 20 66 65 77 20 74 69 6d 65   most a few time
2afe0 73 20 61 6e 64 20 74 68 65 6e 20 64 65 73 74 72  s and then destr
2aff0 6f 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  oyed using.** [s
2b000 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2b010 29 5d 20 72 65 6c 61 74 69 76 65 6c 79 20 73 6f  )] relatively so
2b020 6f 6e 2e 20 54 68 65 20 63 75 72 72 65 6e 74 20  on. The current 
2b030 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61  implementation a
2b040 63 74 73 0a 2a 2a 20 6f 6e 20 74 68 69 73 20 68  cts.** on this h
2b050 69 6e 74 20 62 79 20 61 76 6f 69 64 69 6e 67 20  int by avoiding 
2b060 74 68 65 20 75 73 65 20 6f 66 20 5b 6c 6f 6f 6b  the use of [look
2b070 61 73 69 64 65 20 6d 65 6d 6f 72 79 5d 20 73 6f  aside memory] so
2b080 20 61 73 20 6e 6f 74 20 74 6f 0a 2a 2a 20 64 65   as not to.** de
2b090 70 6c 65 74 65 20 74 68 65 20 6c 69 6d 69 74 65  plete the limite
2b0a0 64 20 73 74 6f 72 65 20 6f 66 20 6c 6f 6f 6b 61  d store of looka
2b0b0 73 69 64 65 20 6d 65 6d 6f 72 79 2e 20 46 75 74  side memory. Fut
2b0c0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 0a  ure versions of.
2b0d0 2a 2a 20 53 51 4c 69 74 65 20 6d 61 79 20 61 63  ** SQLite may ac
2b0e0 74 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 64  t on this hint d
2b0f0 69 66 66 65 72 65 6e 74 6c 79 2e 0a 2a 2a 20 3c  ifferently..** <
2b100 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
2b110 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50  SQLITE_PREPARE_P
2b120 45 52 53 49 53 54 45 4e 54 20 20 20 20 20 20 20  ERSISTENT       
2b130 20 20 20 20 20 20 20 30 78 30 31 0a 0a 2f 2a 0a         0x01../*.
2b140 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
2b150 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
2b160 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f  atement.** KEYWO
2b170 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
2b180 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
2b190 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2b1a0 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a  .** CONSTRUCTOR:
2b1b0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2b1c0 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
2b1d0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  n SQL statement,
2b1e0 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
2b1f0 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
2b200 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
2b210 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
2b220 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2b230 65 73 2e 20 20 4f 72 2c 20 69 6e 20 6f 74 68 65  es.  Or, in othe
2b240 72 20 77 6f 72 64 73 2c 20 74 68 65 73 65 20 72  r words, these r
2b250 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 63  outines.** are c
2b260 6f 6e 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20  onstructors for 
2b270 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2b280 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e  atement] object.
2b290 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 66 65  .**.** The prefe
2b2a0 72 72 65 64 20 72 6f 75 74 69 6e 65 20 74 6f 20  rred routine to 
2b2b0 75 73 65 20 69 73 20 5b 73 71 6c 69 74 65 33 5f  use is [sqlite3_
2b2c0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 20 20  prepare_v2()].  
2b2d0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
2b2e0 70 72 65 70 61 72 65 28 29 5d 20 69 6e 74 65 72  prepare()] inter
2b2f0 66 61 63 65 20 69 73 20 6c 65 67 61 63 79 20 61  face is legacy a
2b300 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f  nd should be avo
2b310 69 64 65 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65  ided..** [sqlite
2b320 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20  3_prepare_v3()] 
2b330 68 61 73 20 61 6e 20 65 78 74 72 61 20 22 70 72  has an extra "pr
2b340 65 70 46 6c 61 67 73 22 20 6f 70 74 69 6f 6e 20  epFlags" option 
2b350 74 68 61 74 20 69 73 20 75 73 65 64 0a 2a 2a 20  that is used.** 
2b360 66 6f 72 20 73 70 65 63 69 61 6c 20 70 75 72 70  for special purp
2b370 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  oses..**.** The 
2b380 75 73 65 20 6f 66 20 74 68 65 20 55 54 46 2d 38  use of the UTF-8
2b390 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 70   interfaces is p
2b3a0 72 65 66 65 72 72 65 64 2c 20 61 73 20 53 51 4c  referred, as SQL
2b3b0 69 74 65 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a  ite currently.**
2b3c0 20 64 6f 65 73 20 61 6c 6c 20 70 61 72 73 69 6e   does all parsin
2b3d0 67 20 75 73 69 6e 67 20 55 54 46 2d 38 2e 20 20  g using UTF-8.  
2b3e0 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72  The UTF-16 inter
2b3f0 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
2b400 65 64 0a 2a 2a 20 61 73 20 61 20 63 6f 6e 76 65  ed.** as a conve
2b410 6e 69 65 6e 63 65 2e 20 20 54 68 65 20 55 54 46  nience.  The UTF
2b420 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73 20 77  -16 interfaces w
2b430 6f 72 6b 20 62 79 20 63 6f 6e 76 65 72 74 69 6e  ork by convertin
2b440 67 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 74  g the.** input t
2b450 65 78 74 20 69 6e 74 6f 20 55 54 46 2d 38 2c 20  ext into UTF-8, 
2b460 74 68 65 6e 20 69 6e 76 6f 6b 69 6e 67 20 74 68  then invoking th
2b470 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2b480 55 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65 2e  UTF-8 interface.
2b490 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
2b4a0 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
2b4b0 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
2b4c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
2b4d0 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
2b4e0 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
2b4f0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2b500 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2b510 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
2b520 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2b530 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74  n16()].  The dat
2b540 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2b550 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
2b560 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  een closed..**.*
2b570 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
2b580 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
2b590 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
2b5a0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
2b5b0 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
2b5c0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
2b5d0 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
2b5e0 65 33 5f 70 72 65 70 61 72 65 28 29 2c 20 73 71  e3_prepare(), sq
2b5f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2b600 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  (),.** and sqlit
2b610 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 0a  e3_prepare_v3().
2b620 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
2b630 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c  e UTF-8, and sql
2b640 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2b650 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  , sqlite3_prepar
2b660 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64  e16_v2(),.** and
2b670 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2b680 31 36 5f 76 33 28 29 20 75 73 65 20 55 54 46 2d  16_v3() use UTF-
2b690 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
2b6a0 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
2b6b0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2b6c0 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
2b6d0 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72  up to the.** fir
2b6e0 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
2b6f0 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73  or. ^If nByte is
2b700 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20   positive, then 
2b710 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  it is the.** num
2b720 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61  ber of bytes rea
2b730 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49  d from zSql.  ^I
2b740 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c  f nByte is zero,
2b750 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65   then no prepare
2b760 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
2b770 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20  s generated..** 
2b780 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
2b790 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70  ows that the sup
2b7a0 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
2b7b0 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
2b7c0 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73  then.** there is
2b7d0 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d   a small perform
2b7e0 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
2b7f0 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  o passing an nBy
2b800 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
2b810 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  t.** is the numb
2b820 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2b830 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
2b840 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
2b850 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
2b860 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  inator..**.** ^I
2b870 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
2b880 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
2b890 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
2b8a0 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
2b8b0 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
2b8c0 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
2b8d0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
2b8e0 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
2b8f0 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
2b900 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
2b910 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
2b920 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
2b930 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
2b940 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
2b950 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
2b960 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
2b970 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
2b980 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
2b990 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b9a0 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
2b9b0 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
2b9c0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
2b9d0 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
2b9e0 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
2b9f0 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
2ba00 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
2ba10 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
2ba20 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
2ba30 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
2ba40 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
2ba50 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
2ba60 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
2ba70 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
2ba80 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
2ba90 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
2baa0 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
2bab0 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
2bac0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
2bad0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
2bae0 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
2baf0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
2bb00 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
2bb10 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
2bb20 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
2bb30 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
2bb40 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
2bb50 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
2bb60 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2bb70 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
2bb80 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
2bb90 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2bba0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
2bbb0 65 70 61 72 65 5f 76 32 28 29 2c 20 73 71 6c 69  epare_v2(), sqli
2bbc0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2bbd0 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  , sqlite3_prepar
2bbe0 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64  e16_v2(),.** and
2bbf0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2bc00 31 36 5f 76 33 28 29 20 69 6e 74 65 72 66 61 63  16_v3() interfac
2bc10 65 73 20 61 72 65 20 72 65 63 6f 6d 6d 65 6e 64  es are recommend
2bc20 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70  ed for all new p
2bc30 72 6f 67 72 61 6d 73 2e 0a 2a 2a 20 54 68 65 20  rograms..** The 
2bc40 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
2bc50 20 28 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   (sqlite3_prepar
2bc60 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
2bc70 70 72 65 70 61 72 65 31 36 28 29 29 0a 2a 2a 20  prepare16()).** 
2bc80 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
2bc90 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
2bca0 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
2bcb0 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
2bcc0 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74  uraged..** ^In t
2bcd0 68 65 20 22 76 58 22 20 69 6e 74 65 72 66 61 63  he "vX" interfac
2bce0 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
2bcf0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
2bd00 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
2bd10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
2bd20 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
2bd30 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
2bd40 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
2bd50 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
2bd60 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
2bd70 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
2bd80 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
2bd90 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
2bda0 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  hree ways:.**.**
2bdb0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
2bdc0 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
2bdd0 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
2bde0 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
2bdf0 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
2be00 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
2be10 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
2be20 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
2be30 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
2be40 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
2be50 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
2be60 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
2be70 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41   run it again. A
2be80 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54  s many as [SQLIT
2be90 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54  E_MAX_SCHEMA_RET
2bea0 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77  RY].** retries w
2beb0 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65  ill occur before
2bec0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2bed0 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74  gives up and ret
2bee0 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a  urns an error..*
2bef0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
2bf00 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65  i>.** ^When an e
2bf10 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
2bf20 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
2bf30 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
2bf40 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
2bf50 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
2bf60 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
2bf70 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20  r codes].  ^The 
2bf80 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
2bf90 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
2bfa0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
2bfb0 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
2bfc0 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
2bfd0 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
2bfe0 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61  ode.** and the a
2bff0 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64  pplication would
2c000 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
2c010 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
2c020 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2c030 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
2c040 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
2c050 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
2c060 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
2c070 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
2c080 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
2c090 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
2c0a0 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
2c0b0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
2c0c0 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
2c0d0 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
2c0e0 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
2c0f0 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20  fic value bound 
2c100 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20  to [parameter | 
2c110 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20  host parameter] 
2c120 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45  in the .** WHERE
2c130 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e   clause might in
2c140 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69  fluence the choi
2c150 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
2c160 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
2c170 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74  ,.** then the st
2c180 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
2c190 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
2c1a0 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20  compiled, as if 
2c1b0 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a  there had been .
2c1c0 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  ** a schema chan
2c1d0 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ge, on the first
2c1e0 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28    [sqlite3_step(
2c1f0 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e  )] call followin
2c200 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20  g any change.** 
2c210 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2c220 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64  bind_text | bind
2c230 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70  ings] of that [p
2c240 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e  arameter]. .** ^
2c250 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  The specific val
2c260 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75  ue of WHERE-clau
2c270 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d  se [parameter] m
2c280 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
2c290 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66  he .** choice of
2c2a0 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74   query plan if t
2c2b0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
2c2c0 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69  the left-hand si
2c2d0 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a  de of a [LIKE].*
2c2e0 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  * or [GLOB] oper
2c2f0 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70  ator or if the p
2c300 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70  arameter is comp
2c310 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78  ared to an index
2c320 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64  ed column.** and
2c330 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
2c340 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69  BLE_STAT3] compi
2c350 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
2c360 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f  s enabled..** </
2c370 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e 5e 73 71  li>.**.** <p>^sq
2c380 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2c390 28 29 20 64 69 66 66 65 72 73 20 66 72 6f 6d 20  () differs from 
2c3a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2c3b0 76 32 28 29 20 6f 6e 6c 79 20 69 6e 20 68 61 76  v2() only in hav
2c3c0 69 6e 67 0a 2a 2a 20 74 68 65 20 65 78 74 72 61  ing.** the extra
2c3d0 20 70 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d   prepFlags param
2c3e0 65 74 65 72 2c 20 77 68 69 63 68 20 69 73 20 61  eter, which is a
2c3f0 20 62 69 74 20 61 72 72 61 79 20 63 6f 6e 73 69   bit array consi
2c400 73 74 69 6e 67 20 6f 66 20 7a 65 72 6f 20 6f 72  sting of zero or
2c410 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20  .** more of the 
2c420 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f  [SQLITE_PREPARE_
2c430 50 45 52 53 49 53 54 45 4e 54 7c 53 51 4c 49 54  PERSISTENT|SQLIT
2c440 45 5f 50 52 45 50 41 52 45 5f 2a 5d 20 66 6c 61  E_PREPARE_*] fla
2c450 67 73 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  gs.  ^The.** sql
2c460 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2c470 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b  ) interface work
2c480 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
2c490 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33  me as.** sqlite3
2c4a0 5f 70 72 65 70 61 72 65 5f 76 33 28 29 20 77 69  _prepare_v3() wi
2c4b0 74 68 20 61 20 7a 65 72 6f 20 70 72 65 70 46 6c  th a zero prepFl
2c4c0 61 67 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ags parameter..*
2c4d0 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ol>.*/.int s
2c4e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
2c4f0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2c500 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2c510 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2c520 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
2c530 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2c540 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2c550 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
2c560 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2c570 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2c580 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2c590 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2c5a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2c5b0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2c5c0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2c5d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2c5e0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2c5f0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2c600 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2c610 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
2c620 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2c630 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
2c640 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2c650 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2c660 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2c670 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
2c680 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2c690 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
2c6a0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2c6b0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2c6c0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2c6d0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2c6e0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2c6f0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2c700 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2c710 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2c720 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
2c730 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2c740 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2c750 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2c760 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2c770 70 72 65 70 61 72 65 5f 76 33 28 0a 20 20 73 71  prepare_v3(.  sq
2c780 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2c790 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2c7a0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2c7b0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
2c7c0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2c7d0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
2c7e0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2c7f0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2c800 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2c810 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2c820 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69  bytes. */.  unsi
2c830 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46 6c 61  gned int prepFla
2c840 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d  gs, /* Zero or m
2c850 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41  ore SQLITE_PREPA
2c860 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73  RE_ flags */.  s
2c870 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2c880 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2c890 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2c8a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2c8b0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2c8c0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2c8d0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2c8e0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2c8f0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2c900 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
2c910 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2c920 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2c930 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2c940 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2c950 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2c960 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
2c970 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2c980 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2c990 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2c9a0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2c9b0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2c9c0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2c9d0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2c9e0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2c9f0 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
2ca00 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2ca10 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2ca20 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2ca30 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
2ca40 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73  repare16_v2(.  s
2ca50 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2ca60 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2ca70 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2ca80 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
2ca90 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2caa0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
2cab0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2cac0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2cad0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2cae0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2caf0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2cb00 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2cb10 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2cb20 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2cb30 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2cb40 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2cb50 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2cb60 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2cb70 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
2cb80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2cb90 36 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v3(.  sqlite3 
2cba0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2cbb0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2cbc0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2cbd0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
2cbe0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2cbf0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
2cc00 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2cc10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2cc20 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2cc30 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2cc40 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20  . */.  unsigned 
2cc50 69 6e 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f  int prepFlags, /
2cc60 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53  * Zero or more S
2cc70 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66  QLITE_PREPARE_ f
2cc80 6c 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65  lags */.  sqlite
2cc90 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2cca0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2ccb0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2ccc0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
2ccd0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2cce0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2ccf0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2cd00 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
2cd10 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76  API3REF: Retriev
2cd20 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
2cd30 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  L.** METHOD: sql
2cd40 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2cd50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 71 6c  ^The sqlite3_sql
2cd60 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
2cd70 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2cd80 74 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  to a copy of the
2cd90 20 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65   UTF-8.** SQL te
2cda0 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74  xt used to creat
2cdb0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2cdc0 65 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 77 61  ement] P if P wa
2cdd0 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  s.** created by 
2cde0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2cdf0 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2ce00 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 0a  _prepare_v3()],.
2ce10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2ce20 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20  are16_v2()], or 
2ce30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2ce40 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 20 5e 54 68  16_v3()]..** ^Th
2ce50 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  e sqlite3_expand
2ce60 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66  ed_sql(P) interf
2ce70 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2ce80 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38  inter to a UTF-8
2ce90 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  .** string conta
2cea0 69 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65  ining the SQL te
2ceb0 78 74 20 6f 66 20 70 72 65 70 61 72 65 64 20 73  xt of prepared s
2cec0 74 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a  tatement P with.
2ced0 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  ** [bound parame
2cee0 74 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a  ters] expanded..
2cef0 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
2cf00 70 6c 65 2c 20 69 66 20 61 20 70 72 65 70 61 72  ple, if a prepar
2cf10 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ed statement is 
2cf20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68  created using th
2cf30 65 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53  e SQL.** text "S
2cf40 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22  ELECT $abc,:xyz"
2cf50 20 61 6e 64 20 69 66 20 70 61 72 61 6d 65 74 65   and if paramete
2cf60 72 20 24 61 62 63 20 69 73 20 62 6f 75 6e 64 20  r $abc is bound 
2cf70 74 6f 20 69 6e 74 65 67 65 72 20 32 33 34 35 0a  to integer 2345.
2cf80 2a 2a 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72  ** and parameter
2cf90 20 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64   :xyz is unbound
2cfa0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 73  , then sqlite3_s
2cfb0 71 6c 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e  ql() will return
2cfc0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
2cfd0 20 73 74 72 69 6e 67 2c 20 22 53 45 4c 45 43 54   string, "SELECT
2cfe0 20 24 61 62 63 2c 3a 78 79 7a 22 20 62 75 74 20   $abc,:xyz" but 
2cff0 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2d000 5f 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72  _sql().** will r
2d010 65 74 75 72 6e 20 22 53 45 4c 45 43 54 20 32 33  eturn "SELECT 23
2d020 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a  45,NULL".)^.**.*
2d030 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
2d040 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e  xpanded_sql() in
2d050 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2d060 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63  NULL if insuffic
2d070 69 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69  ient memory.** i
2d080 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 68  s available to h
2d090 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 2c 20  old the result, 
2d0a0 6f 72 20 69 66 20 74 68 65 20 72 65 73 75 6c 74  or if the result
2d0b0 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68   would exceed th
2d0c0 65 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d  e.** the maximum
2d0d0 20 73 74 72 69 6e 67 20 6c 65 6e 67 74 68 20 64   string length d
2d0e0 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
2d0f0 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c   [SQLITE_LIMIT_L
2d100 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ENGTH]..**.** ^T
2d110 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
2d120 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d  _SIZE_LIMIT] com
2d130 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
2d140 20 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65   limits the size
2d150 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72   of.** bound par
2d160 61 6d 65 74 65 72 20 65 78 70 61 6e 73 69 6f 6e  ameter expansion
2d170 73 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  s.  ^The [SQLITE
2d180 5f 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d  _OMIT_TRACE] com
2d190 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
2d1a0 69 6f 6e 20 63 61 75 73 65 73 20 73 71 6c 69 74  ion causes sqlit
2d1b0 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2d1c0 29 20 74 6f 20 61 6c 77 61 79 73 20 72 65 74 75  ) to always retu
2d1d0 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  rn NULL..**.** ^
2d1e0 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72  The string retur
2d1f0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  ned by sqlite3_s
2d200 71 6c 28 50 29 20 69 73 20 6d 61 6e 61 67 65 64  ql(P) is managed
2d210 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20 69   by SQLite and i
2d220 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  s.** automatical
2d230 6c 79 20 66 72 65 65 64 20 77 68 65 6e 20 74 68  ly freed when th
2d240 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2d250 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65  ment is finalize
2d260 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e  d..** ^The strin
2d270 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  g returned by sq
2d280 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2d290 71 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74  ql(P), on the ot
2d2a0 68 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20  her hand,.** is 
2d2b0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2d2c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
2d2d0 20 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65   and must be fre
2d2e0 65 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  e by the applica
2d2f0 74 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69  tion.** by passi
2d300 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
2d310 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f  3_free()]..*/.co
2d320 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2d330 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  3_sql(sqlite3_st
2d340 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72  mt *pStmt);.char
2d350 20 2a 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64   *sqlite3_expand
2d360 65 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  ed_sql(sqlite3_s
2d370 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2d380 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2d390 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
2d3a0 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74  L Statement Writ
2d3b0 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a  es The Database.
2d3c0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2d3d0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2d3e0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
2d3f0 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65  readonly(X) inte
2d400 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2d410 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
2d420 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20  .** and only if 
2d430 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2d440 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73  atement] X makes
2d450 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67   no direct chang
2d460 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e  es to.** the con
2d470 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
2d480 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
2d490 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c   Note that [appl
2d4a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2d4b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f  SQL functions] o
2d4c0 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  r.** [virtual ta
2d4d0 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e  bles] might chan
2d4e0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
2d4f0 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20  indirectly as a 
2d500 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a  side effect.  .*
2d510 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
2d520 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
2d530 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e  on defines a fun
2d540 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74  ction "eval()" t
2d550 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73  hat .** calls [s
2d560 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
2d570 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  then the followi
2d580 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
2d590 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65   would.** change
2d5a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2d5b0 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d  le through side-
2d5c0 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  effects:.**.** <
2d5d0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
2d5e0 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76  .**    SELECT ev
2d5f0 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20  al('DELETE FROM 
2d600 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a  t1') FROM t2;.**
2d610 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
2d620 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62  ote>.**.** But b
2d630 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45  ecause the [SELE
2d640 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  CT] statement do
2d650 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
2d660 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a  e database file.
2d670 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c  ** directly, sql
2d680 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2d690 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c  ly() would still
2d6a0 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a   return true.)^.
2d6b0 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69  **.** ^Transacti
2d6c0 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65  on control state
2d6d0 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42  ments such as [B
2d6e0 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c  EGIN], [COMMIT],
2d6f0 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20   [ROLLBACK],.** 
2d700 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64  [SAVEPOINT], and
2d710 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65   [RELEASE] cause
2d720 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2d730 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
2d740 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63  rn true,.** sinc
2d750 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73  e the statements
2d760 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e   themselves do n
2d770 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69  ot actually modi
2d780 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
2d790 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68  but.** rather th
2d7a0 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74  ey control the t
2d7b0 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74  iming of when ot
2d7c0 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d  her statements m
2d7d0 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61  odify the .** da
2d7e0 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41  tabase.  ^The [A
2d7f0 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41  TTACH] and [DETA
2d800 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61  CH] statements a
2d810 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c  lso cause.** sql
2d820 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2d830 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
2d840 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65  rue since, while
2d850 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74   those statement
2d860 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  s.** change the 
2d870 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66  configuration of
2d880 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
2d890 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20  ection, they do 
2d8a0 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61  not make .** cha
2d8b0 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74  nges to the cont
2d8c0 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
2d8d0 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73  ase files on dis
2d8e0 6b 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  k..** ^The sqlit
2d8f0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2d900 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2d910 75 72 6e 73 20 74 72 75 65 20 66 6f 72 20 5b 42  urns true for [B
2d920 45 47 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b  EGIN] since.** [
2d930 42 45 47 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65  BEGIN] merely se
2d940 74 73 20 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67  ts internal flag
2d950 73 2c 20 62 75 74 20 74 68 65 20 5b 42 45 47 49  s, but the [BEGI
2d960 4e 7c 42 45 47 49 4e 20 49 4d 4d 45 44 49 41 54  N|BEGIN IMMEDIAT
2d970 45 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e  E] and.** [BEGIN
2d980 7c 42 45 47 49 4e 20 45 58 43 4c 55 53 49 56 45  |BEGIN EXCLUSIVE
2d990 5d 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f  ] commands do to
2d9a0 75 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65  uch the database
2d9b0 20 61 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74   and so.** sqlit
2d9c0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2d9d0 28 29 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  () returns false
2d9e0 20 66 6f 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61   for those comma
2d9f0 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  nds..*/.int sqli
2da00 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2da10 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  y(sqlite3_stmt *
2da20 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2da30 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
2da40 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64  ne If A Prepared
2da50 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42   Statement Has B
2da60 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54  een Reset.** MET
2da70 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2da80 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2da90 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
2daa0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2dab0 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
2dac0 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70  ro) if the.** [p
2dad0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2dae0 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74  t] S has been st
2daf0 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f  epped at least o
2db00 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  nce using .** [s
2db10 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2db20 62 75 74 20 68 61 73 20 6e 65 69 74 68 65 72 20  but has neither 
2db30 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
2db40 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  n (returned.** [
2db50 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f  SQLITE_DONE] fro
2db60 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  m [sqlite3_step(
2db70 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e  S)]) nor.** been
2db80 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71   reset using [sq
2db90 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e  lite3_reset(S)].
2dba0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
2dbb0 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69  tmt_busy(S).** i
2dbc0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2dbd0 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61   false if S is a
2dbe0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
2dbf0 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a  If S is not a .*
2dc00 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  * NULL pointer a
2dc10 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e  nd is not a poin
2dc20 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b  ter to a valid [
2dc30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2dc40 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74  nt].** object, t
2dc50 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2dc60 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
2dc70 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
2dc80 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  irable..**.** Th
2dc90 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
2dca0 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62   be used in comb
2dcb0 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33  ination [sqlite3
2dcc0 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a  _next_stmt()].**
2dcd0 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70   to locate all p
2dce0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2dcf0 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ts associated wi
2dd00 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a  th a database .*
2dd10 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  * connection tha
2dd20 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66  t are in need of
2dd30 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54   being reset.  T
2dd40 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c  his can be used,
2dd50 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  .** for example,
2dd60 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72   in diagnostic r
2dd70 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63  outines to searc
2dd80 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a  h for prepared .
2dd90 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  ** statements th
2dda0 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61  at are holding a
2ddb0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65   transaction ope
2ddc0 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
2ddd0 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69  3_stmt_busy(sqli
2dde0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2ddf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
2de00 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
2de10 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
2de20 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
2de30 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2de40 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
2de50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
2de60 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
2de70 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
2de80 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
2de90 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
2dea0 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
2deb0 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
2dec0 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
2ded0 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
2dee0 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
2def0 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
2df00 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
2df10 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
2df20 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
2df30 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
2df40 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
2df50 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
2df60 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
2df70 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
2df80 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2df90 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
2dfa0 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
2dfb0 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
2dfc0 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
2dfd0 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
2dfe0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2dff0 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
2e000 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
2e010 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
2e020 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
2e030 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e040 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
2e050 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
2e060 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
2e070 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
2e080 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
2e090 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
2e0a0 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
2e0b0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2e0c0 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
2e0d0 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 20  e3_value_dup()] 
2e0e0 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
2e0f0 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 72 75   used to constru
2e100 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f  ct a new .** pro
2e110 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2e120 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70  alue from an unp
2e130 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2e140 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
2e150 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
2e160 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
2e170 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
2e180 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
2e190 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
2e1a0 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d  .  An internal m
2e1b0 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
2e1c0 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   a protected.** 
2e1d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2e1e0 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65  ject but no mute
2e1f0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e  x is held for an
2e200 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
2e210 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2e220 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65  ject.  If SQLite
2e230 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   is compiled to 
2e240 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  be single-thread
2e250 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c  ed.** (with [SQL
2e260 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
2e270 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69  ] and with [sqli
2e280 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
2e290 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a  ] returning 0).*
2e2a0 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69  * or if SQLite i
2e2b0 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20  s run in one of 
2e2c0 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f  reduced mutex mo
2e2d0 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  des .** [SQLITE_
2e2e0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
2e2f0 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  EAD] or [SQLITE_
2e300 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2e310 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72  AD].** then ther
2e320 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74  e is no distinct
2e330 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
2e340 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
2e350 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2e360 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61  _value objects a
2e370 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75  nd they can be u
2e380 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61  sed interchangea
2e390 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  bly.  However,.*
2e3a0 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f  * for maximum co
2e3b0 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69  de portability i
2e3c0 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
2e3d0 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
2e3e0 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65  ns.** still make
2e3f0 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
2e400 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
2e410 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
2e420 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2e430 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e  lue objects even
2e440 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74   when not strict
2e450 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  ly required..**.
2e460 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2e470 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68  value objects th
2e480 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73  at are passed as
2e490 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f   parameters into
2e4a0 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
2e4b0 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69  tation of [appli
2e4c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2e4d0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72  QL functions] ar
2e4e0 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  e protected..** 
2e4f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
2e500 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ue object return
2e510 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
2e520 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
2e530 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64  ] is unprotected
2e540 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64  ..** Unprotected
2e550 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2e560 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20  bjects may only 
2e570 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20  be used with.** 
2e580 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2e590 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
2e5a0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
2e5b0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ()]..** The [sql
2e5c0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20  ite3_value_blob 
2e5d0 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  | sqlite3_value_
2e5e0 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f  type()] family o
2e5f0 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  f.** interfaces 
2e600 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65  require protecte
2e610 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2e620 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65  objects..*/.type
2e630 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2e640 65 33 5f 76 61 6c 75 65 20 73 71 6c 69 74 65 33  e3_value sqlite3
2e650 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
2e660 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
2e670 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
2e680 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
2e690 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
2e6a0 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
2e6b0 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
2e6c0 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
2e6d0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
2e6e0 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
2e6f0 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
2e700 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
2e710 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
2e720 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
2e730 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2e740 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
2e750 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
2e760 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2e770 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2e780 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
2e790 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
2e7a0 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
2e7b0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2e7c0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
2e7d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
2e7e0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
2e7f0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2e800 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
2e810 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
2e820 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
2e830 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
2e840 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2e850 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
2e860 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
2e870 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
2e880 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2e890 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
2e8a0 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
2e8b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
2e8c0 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
2e8d0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2e8e0 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
2e8f0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
2e900 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
2e910 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
2e920 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
2e930 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
2e940 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
2e950 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
2e960 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45  r binding}.** ME
2e970 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2e980 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  mt.**.** ^(In th
2e990 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2e9a0 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73  text input to [s
2e9b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2e9c0 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  2()] and its var
2e9d0 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61  iants,.** litera
2e9e0 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63  ls may be replac
2e9f0 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74  ed by a [paramet
2ea00 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73  er] that matches
2ea10 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e   one of followin
2ea20 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a  g.** templates:.
2ea30 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2ea40 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f  i>  ?.** <li>  ?
2ea50 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56  NNN.** <li>  :VV
2ea60 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a  V.** <li>  @VVV.
2ea70 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a  ** <li>  $VVV.**
2ea80 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
2ea90 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62  the templates ab
2eaa0 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65  ove, NNN represe
2eab0 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c  nts an integer l
2eac0 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56  iteral,.** and V
2ead0 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  VV represents an
2eae0 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64   alphanumeric id
2eaf0 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68  entifier.)^  ^Th
2eb00 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73  e values of thes
2eb10 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  e.** parameters 
2eb20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
2eb30 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
2eb40 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61  es" or "SQL para
2eb50 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20  meters").** can 
2eb60 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65  be set using the
2eb70 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2eb80 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  ) routines defin
2eb90 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed here..**.** ^
2eba0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2ebb0 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
2ebc0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2ebd0 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a  nes is always.**
2ebe0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2ebf0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
2ec00 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2ec10 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
2ec20 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2ec30 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
2ec40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
2ec50 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
2ec60 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2ec70 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f  SQL parameter to
2ec80 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65   be set..** ^The
2ec90 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61   leftmost SQL pa
2eca0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
2ecb0 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65  ndex of 1.  ^Whe
2ecc0 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
2ecd0 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
2ece0 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
2ecf0 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
2ed00 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
2ed10 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
2ed20 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
2ed30 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
2ed40 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e  occurrence..** ^
2ed50 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61  The index for na
2ed60 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
2ed70 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
2ed80 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
2ed90 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2eda0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50  eter_index()] AP
2edb0 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e  I if desired.  ^
2edc0 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72  The index.** for
2edd0 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65   "?NNN" paramete
2ede0 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  rs is the value 
2edf0 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20  of NNN..** ^The 
2ee00 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62  NNN value must b
2ee10 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20  e between 1 and 
2ee20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  the [sqlite3_lim
2ee30 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74  it()].** paramet
2ee40 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  er [SQLITE_LIMIT
2ee50 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
2ee60 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  ] (default value
2ee70 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  : 999)..**.** ^T
2ee80 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
2ee90 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74  t is the value t
2eea0 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61  o bind to the pa
2eeb0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
2eec0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2eed0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2eee0 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
2eef0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2ef00 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  6().** or sqlite
2ef10 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
2ef20 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2ef30 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
2ef40 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20  parameter.** is 
2ef50 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20  ignored and the 
2ef60 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68  end result is th
2ef70 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65  e same as sqlite
2ef80 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a  3_bind_null()..*
2ef90 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20  *.** ^(In those 
2efa0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
2efb0 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
2efc0 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
2efd0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2efe0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2eff0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
2f000 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
2f010 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
2f020 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
2f030 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
2f040 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
2f050 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
2f060 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f  )^.** ^If the fo
2f070 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2f080 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2f090 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
2f0a0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
2f0b0 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
2f0c0 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  hen the length o
2f0d0 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
2f0e0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2f0f0 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
2f100 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
2f110 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68  inator..** If th
2f120 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2f130 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2f140 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67  nd_blob() is neg
2f150 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74  ative, then.** t
2f160 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
2f170 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
2f180 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66  a non-negative f
2f190 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2f1a0 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  is provided to s
2f1b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2f1c0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2f1d0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f  _bind_text16() o
2f1e0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2f1f0 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20  ext64() then.** 
2f200 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d  that parameter m
2f210 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
2f220 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20  offset.** where 
2f230 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
2f240 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61  or would occur a
2f250 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69  ssuming the stri
2f260 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74  ng were NUL.** t
2f270 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61  erminated.  If a
2f280 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72  ny NUL character
2f290 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20  s occur at byte 
2f2a0 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61  offsets less tha
2f2b0 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n .** the value 
2f2c0 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
2f2d0 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65  rameter then the
2f2e0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
2f2f0 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20  g value will.** 
2f300 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
2f310 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75   NULs.  The resu
2f320 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e  lt of expression
2f330 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69  s involving stri
2f340 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65  ngs.** with embe
2f350 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64  dded NULs is und
2f360 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2f370 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2f380 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e  t to the BLOB an
2f390 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67  d string binding
2f3a0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
2f3b0 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
2f3c0 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
2f3d0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
2f3e0 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
2f3f0 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
2f400 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65  d with it.  ^The
2f410 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
2f420 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70  alled.** to disp
2f430 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
2f440 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69  or string even i
2f450 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69  f the call to bi
2f460 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a  nd API fails..**
2f470 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
2f480 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68  rgument is.** th
2f490 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
2f4a0 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
2f4b0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
2f4c0 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
2f4d0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
2f4e0 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e  in static, unman
2f4f0 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64  aged space and d
2f500 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
2f510 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  be freed..** ^If
2f520 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
2f530 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
2f540 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
2f550 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
2f560 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
2f570 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
2f580 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
2f590 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
2f5a0 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
2f5b0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
2f5c0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
2f5d0 54 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65  The sixth argume
2f5e0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
2f5f0 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74  nd_text64() must
2f600 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53   be one of.** [S
2f610 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
2f620 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51  LITE_UTF16], [SQ
2f630 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f  LITE_UTF16BE], o
2f640 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
2f650 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79  E].** to specify
2f660 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66   the encoding of
2f670 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65   the text in the
2f680 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2f690 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78  .  If.** the six
2f6a0 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
2f6b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2f6c0 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  64() is not one 
2f6d0 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65  of the.** allowe
2f6e0 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61  d values shown a
2f6f0 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20  bove, or if the 
2f700 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73  text encoding is
2f710 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72   different.** fr
2f720 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  om the encoding 
2f730 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
2f740 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
2f750 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2f760 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ior.** is undefi
2f770 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2f780 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2f790 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
2f7a0 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
2f7b0 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
2f7c0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
2f7d0 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f  zeroes.  ^A zero
2f7e0 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
2f7f0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
2f800 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
2f810 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
2f820 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  ts size) while i
2f830 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
2f840 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
2f850 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
2f860 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
2f870 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
2f880 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
2f890 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
2f8a0 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tten using.** [s
2f8b0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
2f8c0 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
2f8d0 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
2f8e0 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76  s..** ^A negativ
2f8f0 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  e value for the 
2f900 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
2f910 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
2f920 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54  h BLOB..**.** ^T
2f930 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2f940 70 6f 69 6e 74 65 72 28 53 2c 49 2c 50 2c 54 2c  pointer(S,I,P,T,
2f950 44 29 20 72 6f 75 74 69 6e 65 20 63 61 75 73 65  D) routine cause
2f960 73 20 74 68 65 20 49 2d 74 68 20 70 61 72 61 6d  s the I-th param
2f970 65 74 65 72 20 69 6e 0a 2a 2a 20 5b 70 72 65 70  eter in.** [prep
2f980 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2f990 53 20 74 6f 20 68 61 76 65 20 61 6e 20 53 51 4c  S to have an SQL
2f9a0 20 76 61 6c 75 65 20 6f 66 20 4e 55 4c 4c 2c 20   value of NULL, 
2f9b0 62 75 74 20 74 6f 20 61 6c 73 6f 20 62 65 0a 2a  but to also be.*
2f9c0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
2f9d0 68 20 74 68 65 20 70 6f 69 6e 74 65 72 20 50 20  h the pointer P 
2f9e0 6f 66 20 74 79 70 65 20 54 2e 20 20 5e 44 20 69  of type T.  ^D i
2f9f0 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
2fa00 70 6f 69 6e 74 65 72 20 6f 72 0a 2a 2a 20 61 20  pointer or.** a 
2fa10 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65 73  pointer to a des
2fa20 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
2fa30 20 66 6f 72 20 50 2e 20 5e 53 51 4c 69 74 65 20   for P. ^SQLite 
2fa40 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 0a  will invoke the.
2fa50 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 20 44 20  ** destructor D 
2fa60 77 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72  with a single ar
2fa70 67 75 6d 65 6e 74 20 6f 66 20 50 20 77 68 65 6e  gument of P when
2fa80 20 69 74 20 69 73 20 66 69 6e 69 73 68 65 64 20   it is finished 
2fa90 75 73 69 6e 67 0a 2a 2a 20 50 2e 20 20 54 68 65  using.** P.  The
2faa0 20 54 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f   T parameter sho
2fab0 75 6c 64 20 62 65 20 61 20 73 74 61 74 69 63 20  uld be a static 
2fac0 73 74 72 69 6e 67 2c 20 70 72 65 66 65 72 61 62  string, preferab
2fad0 6c 79 20 61 20 73 74 72 69 6e 67 0a 2a 2a 20 6c  ly a string.** l
2fae0 69 74 65 72 61 6c 2e 20 54 68 65 20 73 71 6c 69  iteral. The sqli
2faf0 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72  te3_bind_pointer
2fb00 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  () routine is pa
2fb10 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 6f  rt of the.** [po
2fb20 69 6e 74 65 72 20 70 61 73 73 69 6e 67 20 69 6e  inter passing in
2fb30 74 65 72 66 61 63 65 5d 20 61 64 64 65 64 20 66  terface] added f
2fb40 6f 72 20 53 51 4c 69 74 65 20 33 2e 32 30 2e 30  or SQLite 3.20.0
2fb50 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20  ..**.** ^If any 
2fb60 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  of the sqlite3_b
2fb70 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2fb80 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68   are called with
2fb90 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
2fba0 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  ** for the [prep
2fbb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2fbc0 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72  or with a prepar
2fbd0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72  ed statement for
2fbe0 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
2fbf0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62  e3_step()] has b
2fc00 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20  een called more 
2fc10 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73  recently than [s
2fc20 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
2fc30 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c  .** then the cal
2fc40 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  l will return [S
2fc50 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2fc60 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62  If any sqlite3_b
2fc70 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ind_().** routin
2fc80 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70  e is passed a [p
2fc90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2fca0 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e  t] that has been
2fcb0 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a   finalized, the.
2fcc0 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  ** result is und
2fcd0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
2fce0 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
2fcf0 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65  ** ^Bindings are
2fd00 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
2fd10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
2fd20 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
2fd30 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  * ^Unbound param
2fd40 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
2fd50 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
2fd60 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2fd70 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65  3_bind_* routine
2fd80 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
2fd90 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
2fda0 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  or an.** [error 
2fdb0 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e  code] if anythin
2fdc0 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
2fdd0 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47   ^[SQLITE_TOOBIG
2fde0 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2fdf0 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20  ned if the size 
2fe00 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  of a string or B
2fe10 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c  LOB.** exceeds l
2fe20 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79  imits imposed by
2fe30 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
2fe40 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  ([SQLITE_LIMIT_L
2fe50 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53  ENGTH]) or.** [S
2fe60 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48  QLITE_MAX_LENGTH
2fe70 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52  ]..** ^[SQLITE_R
2fe80 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
2fe90 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
2fea0 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
2feb0 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b  ut of range.  ^[
2fec0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
2fed0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
2fee0 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a  loc() fails..**.
2fef0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2ff00 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2ff10 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
2ff20 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2ff30 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
2ff40 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
2ff50 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2ff60 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
2ff70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2ff80 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
2ff90 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2ffa0 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
2ffb0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
2ffc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2ffd0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2ffe0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
2fff0 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  d*, sqlite3_uint
30000 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
30010 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
30020 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
30030 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
30040 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
30050 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
30060 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
30070 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
30080 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
30090 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
300a0 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
300b0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
300c0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
300d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
300e0 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
300f0 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
30100 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
30110 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63  ite3_stmt*,int,c
30120 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76  onst char*,int,v
30130 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
30140 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
30150 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
30160 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
30170 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
30180 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
30190 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
301a0 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73  text64(sqlite3_s
301b0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
301c0 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f   char*, sqlite3_
301d0 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20  uint64,.        
301e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
301f0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c   void(*)(void*),
30200 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65   unsigned char e
30210 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71  ncoding);.int sq
30220 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
30230 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30240 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
30250 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
30260 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69  sqlite3_bind_poi
30270 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 73 74 6d  nter(sqlite3_stm
30280 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20  t*, int, void*, 
30290 63 6f 6e 73 74 20 63 68 61 72 2a 2c 76 6f 69 64  const char*,void
302a0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
302b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
302c0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
302d0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
302e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
302f0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73  ind_zeroblob64(s
30300 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30310 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  t, sqlite3_uint6
30320 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  4);../*.** CAPI3
30330 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
30340 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  QL Parameters.**
30350 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
30360 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  _stmt.**.** ^Thi
30370 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
30380 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
30390 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
303a0 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
303b0 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
303c0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
303d0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
303e0 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
303f0 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
30400 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
30410 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
30420 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
30430 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
30440 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
30450 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
30460 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
30470 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
30480 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
30490 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
304a0 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
304b0 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
304c0 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
304d0 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
304e0 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
304f0 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
30500 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
30510 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
30520 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
30530 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
30540 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
30550 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
30560 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
30570 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
30580 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
30590 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
305a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
305b0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
305c0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
305d0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
305e0 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
305f0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
30600 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
30610 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
30620 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
30630 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
30640 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30650 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
30660 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st Parameter.** 
30670 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
30680 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
30690 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
306a0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29  ameter_name(P,N)
306b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
306c0 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ns.** the name o
306d0 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20  f the N-th [SQL 
306e0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
306f0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
30700 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53  ement] P..** ^(S
30710 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  QL parameters of
30720 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
30730 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
30740 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
30750 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68  * have a name wh
30760 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
30770 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  g "?NNN" or ":AA
30780 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
30790 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63  "$AAA".** respec
307a0 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74  tively..** In ot
307b0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
307c0 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
307d0 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a  " or "@" or "?".
307e0 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
307f0 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
30800 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65  me.)^.** ^Parame
30810 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
30820 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
30830 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
30840 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
30850 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65   and are referre
30860 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73  d to as "nameles
30870 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73  s" or "anonymous
30880 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
30890 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68  .** ^The first h
308a0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
308b0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
308c0 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49   not 0..**.** ^I
308d0 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73  f the value N is
308e0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
308f0 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72   if the N-th par
30900 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
30910 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
30920 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   is returned.  ^
30930 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
30940 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
30950 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
30960 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
30970 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
30980 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
30990 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
309a0 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
309b0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a  _prepare16()],.*
309c0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
309d0 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b  re16_v2()], or [
309e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
309f0 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v3()]..**.** S
30a00 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
30a10 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
30a20 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
30a30 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
30a40 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
30a50 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
30a60 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
30a70 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f  _index()]..*/.co
30a80 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
30a90 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
30aa0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
30ab0 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
30ac0 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
30ad0 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
30ae0 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
30af0 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  me.** METHOD: sq
30b00 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
30b10 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64   ^Return the ind
30b20 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
30b30 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
30b40 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20   name.  ^The.** 
30b50 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
30b60 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
30b70 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
30b80 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
30b90 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
30ba0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
30bb0 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a  3_bind()].  ^A z
30bc0 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
30bd0 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
30be0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
30bf0 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61  ound.  ^The para
30c00 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
30c10 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
30c20 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
30c30 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
30c40 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
30c50 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
30c60 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
30c70 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
30c80 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
30c90 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
30ca0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
30cb0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
30cc0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
30cd0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
30ce0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
30cf0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
30d00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
30d10 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
30d20 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
30d30 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
30d40 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
30d50 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
30d60 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
30d70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
30d80 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
30d90 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
30da0 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f  atement.** METHO
30db0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
30dc0 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
30dd0 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
30de0 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
30df0 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
30e00 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
30e10 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
30e20 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
30e30 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
30e40 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
30e50 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
30e60 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
30e70 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
30e80 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
30e90 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
30ea0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
30eb0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
30ec0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
30ed0 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
30ee0 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult Set.** METHO
30ef0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
30f00 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
30f10 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
30f20 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
30f30 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
30f40 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  y the.** [prepar
30f50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
30f60 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
30f70 72 65 74 75 72 6e 73 20 30 2c 20 74 68 61 74 20  returns 0, that 
30f80 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70  means the .** [p
30f90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30fa0 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20 64 61  t] returns no da
30fb0 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
30fc0 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
30fd0 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73 74 20   ^However, just 
30fe0 62 65 63 61 75 73 65 20 74 68 69 73 20 72 6f 75  because this rou
30ff0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
31000 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 20 64  ositive number d
31010 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20  oes not.** mean 
31020 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  that one or more
31030 20 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77 69   rows of data wi
31040 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ll be returned. 
31050 20 5e 41 20 53 45 4c 45 43 54 20 73 74 61 74 65   ^A SELECT state
31060 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77  ment.** will alw
31070 61 79 73 20 68 61 76 65 20 61 20 70 6f 73 69 74  ays have a posit
31080 69 76 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ive sqlite3_colu
31090 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74 20 64  mn_count() but d
310a0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a  epending on the.
310b0 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ** WHERE clause 
310c0 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20  constraints and 
310d0 74 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e  the table conten
310e0 74 2c 20 69 74 20 6d 69 67 68 74 20 72 65 74 75  t, it might retu
310f0 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a  rn no rows..**.*
31100 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
31110 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
31120 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )].*/.int sqlite
31130 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73  3_column_count(s
31140 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
31150 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
31160 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d  3REF: Column Nam
31170 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  es In A Result S
31180 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
31190 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
311a0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
311b0 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
311c0 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
311d0 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
311e0 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
311f0 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
31200 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
31210 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
31220 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
31230 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
31240 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
31250 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
31260 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
31270 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
31280 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
31290 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
312a0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
312b0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
312c0 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
312d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
312e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
312f0 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
31300 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
31310 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
31320 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
31330 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
31340 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
31350 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
31360 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
31370 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
31380 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
31390 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
313a0 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
313b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
313c0 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
313d0 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
313e0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
313f0 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
31400 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
31410 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
31420 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
31430 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
31440 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
31450 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
31460 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
31470 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
31480 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
31490 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
314a0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
314b0 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
314c0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
314d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
314e0 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
314f0 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
31500 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
31510 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
31520 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
31530 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
31540 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
31550 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
31560 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
31570 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
31580 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
31590 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
315a0 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
315b0 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
315c0 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
315d0 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
315e0 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
315f0 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
31600 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
31610 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
31620 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
31630 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
31640 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
31650 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
31660 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
31670 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
31680 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
31690 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
316a0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
316b0 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
316c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
316d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
316e0 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
316f0 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
31700 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
31710 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
31720 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
31730 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20  provide a means 
31740 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  to determine the
31750 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
31760 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63  , and.** table c
31770 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68  olumn that is th
31780 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61  e origin of a pa
31790 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20  rticular result 
317a0 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45  column in.** [SE
317b0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
317c0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
317d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
317e0 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
317f0 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
31800 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
31810 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
31820 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64  string.  ^The _d
31830 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
31840 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
31850 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
31860 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
31870 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
31880 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
31890 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
318a0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
318b0 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
318c0 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
318d0 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20  string is valid 
318e0 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61  until the [prepa
318f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
31900 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75  s destroyed.** u
31910 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
31920 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
31930 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
31940 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
31950 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
31960 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
31970 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
31980 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
31990 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
319a0 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20   until the same 
319b0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
319c0 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69  equested.** agai
319d0 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74  n in a different
319e0 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
319f0 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75   ^The names retu
31a00 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69  rned are the ori
31a10 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64  ginal un-aliased
31a20 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a   names of the.**
31a30 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
31a40 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a  , and column..**
31a50 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
31a60 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65  rgument to these
31a70 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61   interfaces is a
31a80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31a90 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65  ment]..** ^These
31aa0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
31ab0 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
31ac0 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75  out the Nth resu
31ad0 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  lt column return
31ae0 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61  ed by.** the sta
31af0 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
31b00 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
31b10 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
31b20 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f  .** ^The left-mo
31b30 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c  st column is col
31b40 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20  umn 0 for these 
31b50 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
31b60 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
31b70 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  mn returned by t
31b80 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
31b90 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  an expression or
31ba0 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64  .** subquery and
31bb0 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e   is not a column
31bc0 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c   value, then all
31bd0 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
31be0 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55  ons return.** NU
31bf0 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  LL.  ^These rout
31c00 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72  ine might also r
31c10 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20  eturn NULL if a 
31c20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
31c30 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72  n error.** occur
31c40 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20  s.  ^Otherwise, 
31c50 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20  they return the 
31c60 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61  name of the atta
31c70 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74  ched database, t
31c80 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75  able,.** or colu
31c90 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65  mn that query re
31ca0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20  sult column was 
31cb0 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a  extracted from..
31cc0 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61  **.** ^As with a
31cd0 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ll other SQLite 
31ce0 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73  APIs, those whos
31cf0 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68  e names end with
31d00 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20   "16" return.** 
31d10 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73  UTF-16 encoded s
31d20 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f  trings and the o
31d30 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72  ther functions r
31d40 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a  eturn UTF-8..**.
31d50 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61  ** ^These APIs a
31d60 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
31d70 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
31d80 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
31d90 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
31da0 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
31db0 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70  METADATA] C-prep
31dc0 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e  rocessor symbol.
31dd0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
31de0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
31df0 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  ll one or more o
31e00 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
31e10 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d   against the sam
31e20 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  e.** prepared st
31e30 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
31e40 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  mn at the same t
31e50 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
31e60 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65  ults are.** unde
31e70 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  fined..**.** If 
31e80 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
31e90 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
31ea0 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  more.** [sqlite3
31eb0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
31ec0 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d  _name | column m
31ed0 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63  etadata interfac
31ee0 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  es].** for the s
31ef0 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
31f00 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73  atement] and res
31f10 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74  ult column.** at
31f20 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
31f30 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
31f40 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
31f50 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
31f60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
31f70 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74  abase_name(sqlit
31f80 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
31f90 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
31fa0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
31fb0 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  se_name16(sqlite
31fc0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
31fd0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
31fe0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
31ff0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
32000 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
32010 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
32020 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
32030 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
32040 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
32050 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
32060 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  rigin_name(sqlit
32070 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
32080 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
32090 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
320a0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
320b0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
320c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
320d0 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f  lared Datatype O
320e0 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  f A Query Result
320f0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
32100 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
32110 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
32120 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
32130 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
32140 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
32150 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
32160 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
32170 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
32180 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
32190 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
321a0 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
321b0 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
321c0 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
321d0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
321e0 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
321f0 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
32200 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
32210 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
32220 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
32230 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
32240 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
32250 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
32260 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
32270 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
32280 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
32290 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
322a0 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
322b0 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
322c0 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
322d0 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
322e0 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
322f0 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
32300 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
32310 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
32320 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
32330 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
32340 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
32350 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
32360 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
32370 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
32380 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
32390 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
323a0 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
323b0 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
323c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
323d0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
323e0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
323f0 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
32400 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
32410 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
32420 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
32430 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
32440 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
32450 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
32460 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
32470 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
32480 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
32490 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
324a0 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
324b0 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
324c0 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
324d0 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
324e0 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
324f0 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
32500 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
32510 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
32520 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
32530 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
32540 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
32550 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
32560 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
32570 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
32580 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
32590 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
325a0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
325b0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
325c0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
325d0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
325e0 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
325f0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
32600 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
32610 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41  te3_stmt.**.** A
32620 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64  fter a [prepared
32630 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20   statement] has 
32640 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73  been prepared us
32650 69 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73  ing any of.** [s
32660 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
32670 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70  2()], [sqlite3_p
32680 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73  repare_v3()], [s
32690 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
326a0 5f 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  _v2()],.** or [s
326b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
326c0 5f 76 33 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v3()] or one of
326d0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
326e0 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
326f0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
32700 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32710 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
32720 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
32730 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
32740 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
32750 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
32760 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
32770 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
32780 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
32790 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
327a0 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
327b0 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
327c0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
327d0 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
327e0 20 6e 65 77 65 72 20 22 76 58 22 20 69 6e 74 65   newer "vX" inte
327f0 72 66 61 63 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  rfaces.** [sqlit
32800 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
32810 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
32820 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
32830 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
32840 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
32850 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
32860 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
32870 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
32880 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
32890 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
328a0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
328b0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
328c0 0a 2a 2a 20 6e 65 77 20 22 76 58 22 20 69 6e 74  .** new "vX" int
328d0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
328e0 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
328f0 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
32900 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
32910 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
32920 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
32930 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  rted..**.** ^In 
32940 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
32950 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
32960 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
32970 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
32980 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
32990 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
329a0 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
329b0 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
329c0 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74  MISUSE]..** ^Wit
329d0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
329e0 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
329f0 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
32a00 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
32a10 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
32a20 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
32a30 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
32a40 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55  *.** ^[SQLITE_BU
32a50 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
32a60 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
32a70 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
32a80 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
32a90 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
32aa0 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
32ab0 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20  s job.  ^If the 
32ac0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
32ad0 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
32ae0 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
32af0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
32b00 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
32b10 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
32b20 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
32b30 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
32b40 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
32b50 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
32b60 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63  hin an.** explic
32b70 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
32b80 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
32b90 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
32ba0 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
32bb0 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
32bc0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e  .** ^[SQLITE_DON
32bd0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
32be0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
32bf0 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
32c00 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
32c10 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
32c20 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
32c30 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
32c40 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
32c50 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
32c60 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
32c70 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
32c80 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
32c90 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
32ca0 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
32cb0 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
32cc0 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73  ** ^If the SQL s
32cd0 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
32ce0 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
32cf0 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
32d00 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
32d10 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
32d20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
32d30 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
32d40 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
32d50 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
32d60 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
32d70 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
32d80 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
32d90 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
32da0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
32db0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
32dc0 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
32dd0 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
32de0 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ata..**.** ^[SQL
32df0 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
32e00 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
32e10 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
32e20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
32e30 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
32e40 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
32e50 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
32e60 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
32e70 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
32e80 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
32e90 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
32ea0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
32eb0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
32ec0 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61  * ^With the lega
32ed0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
32ee0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
32ef0 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
32f00 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
32f10 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
32f20 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
32f30 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
32f40 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
32f50 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
32f60 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
32f70 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
32f80 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
32f90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
32fa0 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
32fb0 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
32fc0 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
32fd0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
32fe0 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
32ff0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
33000 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
33010 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
33020 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
33030 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
33040 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
33050 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
33060 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
33070 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
33080 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
33090 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
330a0 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
330b0 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
330c0 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
330d0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
330e0 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
330f0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
33100 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
33110 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
33120 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
33130 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33140 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
33150 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
33160 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
33170 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
33180 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  time..**.** For 
33190 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  all versions of 
331a0 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64  SQLite up to and
331b0 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32   including 3.6.2
331c0 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  3.1, a call to.*
331d0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
331e0 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64  ()] was required
331f0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73   after sqlite3_s
33200 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61  tep() returned a
33210 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  nything.** other
33220 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
33230 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75  W] before any su
33240 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
33250 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65  ion of.** sqlite
33260 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75  3_step().  Failu
33270 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  re to reset the 
33280 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
33290 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  nt using .** [sq
332a0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
332b0 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
332c0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
332d0 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a  ] return from.**
332e0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
332f0 20 20 42 75 74 20 61 66 74 65 72 20 5b 76 65 72    But after [ver
33300 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28  sion 3.6.23.1] (
33310 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31  [dateof:3.6.23.1
33320 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ],.** sqlite3_st
33330 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
33340 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
33350 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
33360 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
33370 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
33380 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
33390 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
333a0 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
333b0 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
333c0 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
333d0 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
333e0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
333f0 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
33400 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
33410 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
33420 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
33430 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
33440 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
33450 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
33460 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
33470 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
33480 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
33490 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
334a0 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
334b0 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
334c0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
334d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
334e0 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
334f0 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
33500 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
33510 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
33520 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
33530 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
33540 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
33550 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
33560 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
33570 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
33580 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
33590 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
335a0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
335b0 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
335c0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
335d0 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
335e0 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
335f0 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
33600 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
33610 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
33620 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
33630 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
33640 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
33650 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
33660 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
33670 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
33680 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  nts.** using [sq
33690 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
336a0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
336b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a  prepare_v2()].**
336c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
336d0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
336e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
336f0 31 36 5f 76 33 28 29 5d 20 69 6e 73 74 65 61 64  16_v3()] instead
33700 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
33710 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
33720 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
33730 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
33740 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
33750 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
33760 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
33770 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
33780 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
33790 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
337a0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
337b0 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 20  "vX" interfaces 
337c0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
337d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
337e0 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
337f0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
33800 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63  REF: Number of c
33810 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75  olumns in a resu
33820 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44  lt set.** METHOD
33830 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
33840 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
33850 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
33860 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
33870 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
33880 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a  columns in the.*
33890 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  * current row of
338a0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
338b0 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
338c0 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49  tement] P..** ^I
338d0 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  f prepared state
338e0 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20  ment P does not 
338f0 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61  have results rea
33900 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  dy to return.** 
33910 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68  (via calls to th
33920 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
33930 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  n_int | sqlite3_
33940 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a  column_*()] of.*
33950 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68  * interfaces) th
33960 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  en sqlite3_data_
33970 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73  count(P) returns
33980 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69   0..** ^The sqli
33990 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
339a0 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72  ) routine also r
339b0 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73  eturns 0 if P is
339c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
339d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
339e0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
339f0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
33a00 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
33a10 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
33a20 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
33a30 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44  turned [SQLITE_D
33a40 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  ONE].  ^The sqli
33a50 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
33a60 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e  ).** will return
33a70 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65   non-zero if pre
33a80 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73  vious call to [s
33a90 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
33aa0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c  returned.** [SQL
33ab0 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74  ITE_ROW], except
33ac0 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20   in the case of 
33ad0 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72  the [PRAGMA incr
33ae0 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a  emental_vacuum].
33af0 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61  ** where it alwa
33b00 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20  ys returns zero 
33b10 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20  since each step 
33b20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74  of that multi-st
33b30 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74  ep.** pragma ret
33b40 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f  urns 0 columns o
33b50 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65  f data..**.** Se
33b60 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
33b70 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
33b80 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
33b90 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
33ba0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
33bb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33bc0 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
33bd0 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  tatypes.** KEYWO
33be0 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
33bf0 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76  .**.** ^(Every v
33c00 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
33c10 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
33c20 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
33c30 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
33c40 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
33c50 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
33c60 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
33c70 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
33c80 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
33c90 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
33ca0 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
33cb0 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  L.** </ul>)^.**.
33cc0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
33cd0 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72  ts are codes for
33ce0 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74   each of those t
33cf0 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ypes..**.** Note
33d00 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45   that the SQLITE
33d10 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77  _TEXT constant w
33d20 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20  as also used in 
33d30 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
33d40 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65  .** for a comple
33d50 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d  tely different m
33d60 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72  eaning.  Softwar
33d70 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
33d80 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c  inst both.** SQL
33d90 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e  ite version 2 an
33da0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
33db0 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51   3 should use SQ
33dc0 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a  LITE3_TEXT, not.
33dd0 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
33de0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
33df0 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
33e00 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
33e10 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
33e20 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
33e30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33e40 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
33e50 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
33e60 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
33e70 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
33e80 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
33e90 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
33ea0 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
33eb0 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
33ec0 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c  3REF: Result Val
33ed0 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79  ues From A Query
33ee0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
33ef0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
33f00 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f  ctions}.** METHO
33f10 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
33f20 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72 79  **.** <b>Summary
33f30 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  :</b>.** <blockq
33f40 75 6f 74 65 3e 3c 74 61 62 6c 65 20 62 6f 72 64  uote><table bord
33f50 65 72 3d 30 20 63 65 6c 6c 70 61 64 64 69 6e 67  er=0 cellpadding
33f60 3d 30 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d 30  =0 cellspacing=0
33f70 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  >.** <tr><td><b>
33f80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33f90 6c 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  lob</b><td>&rarr
33fa0 3b 3c 74 64 3e 42 4c 4f 42 20 72 65 73 75 6c 74  ;<td>BLOB result
33fb0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
33fc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
33fd0 75 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  uble</b><td>&rar
33fe0 72 3b 3c 74 64 3e 52 45 41 4c 20 72 65 73 75 6c  r;<td>REAL resul
33ff0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  t.** <tr><td><b>
34000 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
34010 6e 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  nt</b><td>&rarr;
34020 3c 74 64 3e 33 32 2d 62 69 74 20 49 4e 54 45 47  <td>32-bit INTEG
34030 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72  ER result.** <tr
34040 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
34050 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c 2f 62 3e  column_int64</b>
34060 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 36 34  <td>&rarr;<td>64
34070 2d 62 69 74 20 49 4e 54 45 47 45 52 20 72 65 73  -bit INTEGER res
34080 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  ult.** <tr><td><
34090 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
340a0 5f 74 65 78 74 3c 2f 62 3e 3c 74 64 3e 26 72 61  _text</b><td>&ra
340b0 72 72 3b 3c 74 64 3e 55 54 46 2d 38 20 54 45 58  rr;<td>UTF-8 TEX
340c0 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e  T result.** <tr>
340d0 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
340e0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 3c 2f 62 3e  olumn_text16</b>
340f0 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54  <td>&rarr;<td>UT
34100 46 2d 31 36 20 54 45 58 54 20 72 65 73 75 6c 74  F-16 TEXT result
34110 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
34120 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
34130 6c 75 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  lue</b><td>&rarr
34140 3b 3c 74 64 3e 54 68 65 20 72 65 73 75 6c 74 20  ;<td>The result 
34150 61 73 20 61 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74  as an .** [sqlit
34160 65 33 5f 76 61 6c 75 65 7c 75 6e 70 72 6f 74 65  e3_value|unprote
34170 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
34180 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 3c  ue] object..** <
34190 74 72 3e 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64  tr><td>&nbsp;<td
341a0 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70  >&nbsp;<td>&nbsp
341b0 3b 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  ;.** <tr><td><b>
341c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
341d0 79 74 65 73 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  ytes</b><td>&rar
341e0 72 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 61 20  r;<td>Size of a 
341f0 42 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20 55 54 46  BLOB.** or a UTF
34200 2d 38 20 54 45 58 54 20 72 65 73 75 6c 74 20 69  -8 TEXT result i
34210 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c  n bytes.** <tr><
34220 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
34230 6c 75 6d 6e 5f 62 79 74 65 73 31 36 26 6e 62 73  lumn_bytes16&nbs
34240 70 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a 2a 2a 20  p;&nbsp;</b>.** 
34250 3c 74 64 3e 26 72 61 72 72 3b 26 6e 62 73 70 3b  <td>&rarr;&nbsp;
34260 26 6e 62 73 70 3b 3c 74 64 3e 53 69 7a 65 20 6f  &nbsp;<td>Size o
34270 66 20 55 54 46 2d 31 36 0a 2a 2a 20 54 45 58 54  f UTF-16.** TEXT
34280 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72   in bytes.** <tr
34290 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
342a0 63 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f 62 3e 3c  column_type</b><
342b0 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 44 65 66  td>&rarr;<td>Def
342c0 61 75 6c 74 0a 2a 2a 20 64 61 74 61 74 79 70 65  ault.** datatype
342d0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 0a 2a   of the result.*
342e0 2a 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f 63  * </table></bloc
342f0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62  kquote>.**.** <b
34300 3e 44 65 74 61 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a  >Details:</b>.**
34310 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
34320 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
34330 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
34340 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
34350 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
34360 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
34370 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79  uery.  ^In every
34380 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
34390 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
343a0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
343b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
343c0 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
343d0 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
343e0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
343f0 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
34400 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
34410 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
34420 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
34430 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
34440 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
34450 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
34460 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
34470 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
34480 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
34490 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54   be returned. ^T
344a0 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
344b0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
344c0 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
344d0 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75  ex 0..** ^The nu
344e0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
344f0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61  in the result ca
34500 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
34510 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
34520 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
34530 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
34540 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
34550 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
34560 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
34570 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
34580 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
34590 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
345a0 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
345b0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
345c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
345d0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
345e0 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
345f0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
34600 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
34610 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
34620 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
34630 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
34640 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
34650 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
34660 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
34670 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
34680 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
34690 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
346a0 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
346b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
346c0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
346d0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
346e0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
346f0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
34700 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
34710 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
34720 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
34730 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
34740 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
34750 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
34760 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
34770 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
34780 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
34790 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
347a0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
347b0 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
347c0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
347d0 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
347e0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
347f0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
34800 2a 20 54 68 65 20 66 69 72 73 74 20 73 69 78 20  * The first six 
34810 69 6e 74 65 72 66 61 63 65 73 20 28 5f 62 6c 6f  interfaces (_blo
34820 62 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f 69 6e 74  b, _double, _int
34830 2c 20 5f 69 6e 74 36 34 2c 20 5f 74 65 78 74 2c  , _int64, _text,
34840 20 61 6e 64 20 5f 74 65 78 74 31 36 29 0a 2a 2a   and _text16).**
34850 20 65 61 63 68 20 72 65 74 75 72 6e 20 74 68 65   each return the
34860 20 76 61 6c 75 65 20 6f 66 20 61 20 72 65 73 75   value of a resu
34870 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 20 61 20 73  lt column in a s
34880 70 65 63 69 66 69 63 20 64 61 74 61 20 66 6f 72  pecific data for
34890 6d 61 74 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20  mat.  If.** the 
348a0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
348b0 20 6e 6f 74 20 69 6e 69 74 69 61 6c 6c 79 20 69   not initially i
348c0 6e 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  n the requested 
348d0 66 6f 72 6d 61 74 20 28 66 6f 72 20 65 78 61 6d  format (for exam
348e0 70 6c 65 2c 0a 2a 2a 20 69 66 20 74 68 65 20 71  ple,.** if the q
348f0 75 65 72 79 20 72 65 74 75 72 6e 73 20 61 6e 20  uery returns an 
34900 69 6e 74 65 67 65 72 20 62 75 74 20 74 68 65 20  integer but the 
34910 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
34920 65 78 74 28 29 20 69 6e 74 65 72 66 61 63 65 0a  ext() interface.
34930 2a 2a 20 69 73 20 75 73 65 64 20 74 6f 20 65 78  ** is used to ex
34940 74 72 61 63 74 20 74 68 65 20 76 61 6c 75 65 29  tract the value)
34950 20 74 68 65 6e 20 61 6e 20 61 75 74 6f 6d 61 74   then an automat
34960 69 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  ic type conversi
34970 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
34980 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34990 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
349a0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
349b0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
349c0 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
349d0 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
349e0 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
349f0 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
34a00 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
34a10 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
34a20 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
34a30 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
34a40 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
34a50 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
34a60 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
34a70 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
34a80 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20 76  .** The return v
34a90 61 6c 75 65 20 6f 66 20 73 71 6c 69 74 65 33 5f  alue of sqlite3_
34aa0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 63 61  column_type() ca
34ab0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 63  n be used to dec
34ac0 69 64 65 20 77 68 69 63 68 0a 2a 2a 20 6f 66 20  ide which.** of 
34ad0 74 68 65 20 66 69 72 73 74 20 73 69 78 20 69 6e  the first six in
34ae0 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20 62  terface should b
34af0 65 20 75 73 65 64 20 74 6f 20 65 78 74 72 61 63  e used to extrac
34b00 74 20 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c  t the column val
34b10 75 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  ue..** The value
34b20 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
34b30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
34b40 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
34b50 6e 67 66 75 6c 20 69 66 20 6e 6f 0a 2a 2a 20 61  ngful if no.** a
34b60 75 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f  utomatic type co
34b70 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
34b80 63 63 75 72 72 65 64 20 66 6f 72 20 74 68 65 20  ccurred for the 
34b90 76 61 6c 75 65 20 69 6e 20 71 75 65 73 74 69 6f  value in questio
34ba0 6e 2e 20 20 0a 2a 2a 20 41 66 74 65 72 20 61 20  n.  .** After a 
34bb0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
34bc0 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 63   the result of c
34bd0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
34be0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
34bf0 69 73 20 75 6e 64 65 66 69 6e 65 64 2c 20 74 68  is undefined, th
34c00 6f 75 67 68 20 68 61 72 6d 6c 65 73 73 2e 20 20  ough harmless.  
34c10 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
34c20 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
34c30 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
34c40 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
34c50 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
34c60 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
34c70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
34c80 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
34c90 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 61  t is a BLOB or a
34ca0 20 54 45 58 54 20 73 74 72 69 6e 67 2c 20 74 68   TEXT string, th
34cb0 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
34cc0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
34cd0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
34ce0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 69 6e 74  mn_bytes16() int
34cf0 65 72 66 61 63 65 73 20 63 61 6e 20 62 65 20 75  erfaces can be u
34d00 73 65 64 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  sed to determine
34d10 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 6f 66 20   the size.** of 
34d20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
34d30 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ing..**.** ^If t
34d40 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
34d50 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
34d60 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
34d70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
34d80 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  s().** routine r
34d90 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
34da0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
34db0 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
34dc0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
34dd0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
34de0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
34df0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
34e00 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
34e10 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
34e20 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
34e30 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
34e40 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
34e50 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
34e60 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
34e70 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
34e80 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
34e90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
34ea0 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
34eb0 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
34ec0 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
34ed0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
34ee0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
34ef0 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
34f00 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
34f10 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
34f20 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
34f30 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72  mn_bytes() retur
34f40 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
34f50 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
34f60 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31   a BLOB or UTF-1
34f70 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  6 string then th
34f80 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
34f90 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f  _bytes16().** ro
34fa0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
34fb0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
34fc0 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
34fd0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
34fe0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
34ff0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74   UTF-8 string, t
35000 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
35010 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e  mn_bytes16() con
35020 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
35030 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e  ing to UTF-16 an
35040 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
35050 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
35060 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
35070 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
35080 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
35090 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
350a0 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b  es16() uses.** [
350b0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
350c0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
350d0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
350e0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64  TF-16 string and
350f0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
35100 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
35110 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
35120 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
35130 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
35140 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
35150 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73  ytes16() returns
35160 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   zero..**.** ^Th
35170 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
35180 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
35190 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
351a0 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  d .** [sqlite3_c
351b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
351c0 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20   do not include 
351d0 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
351e0 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a  tors at the end.
351f0 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
35200 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a  .  ^For clarity:
35210 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75   the values retu
35220 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
35230 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
35240 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
35250 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
35260 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65  )] are the numbe
35270 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
35280 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
35290 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
352a0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
352b0 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e   ^Strings return
352c0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
352d0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
352e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
352f0 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
35300 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
35310 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d  are always zero-
35320 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
35330 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
35340 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
35350 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
35360 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
35370 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  LOB is a NULL po
35380 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  inter..**.** <b>
35390 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68  Warning:</b> ^Th
353a0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
353b0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
353c0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
353d0 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
353e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
353f0 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61  e] object.  In a
35400 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65   multithreaded e
35410 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61  nvironment,.** a
35420 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
35430 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
35440 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ct may only be u
35450 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a  sed safely with.
35460 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
35470 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
35480 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
35490 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
354a0 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
354b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
354c0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
354d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
354e0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
354f0 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
35500 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
35510 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
35520 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
35530 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
35540 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
35550 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
35560 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
35570 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68  ytes()], the beh
35580 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72  avior is not thr
35590 65 61 64 73 61 66 65 2e 0a 2a 2a 20 48 65 6e 63  eadsafe..** Henc
355a0 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  e, the sqlite3_c
355b0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 20 69 6e  olumn_value() in
355c0 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 6e 6f  terface.** is no
355d0 72 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75 73 65 66  rmally only usef
355e0 75 6c 20 77 69 74 68 69 6e 20 74 68 65 20 69 6d  ul within the im
355f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
35600 0a 2a 2a 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  .** [application
35610 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
35620 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 76 69 72 74  ctions] or [virt
35630 75 61 6c 20 74 61 62 6c 65 73 5d 2c 20 6e 6f 74  ual tables], not
35640 20 77 69 74 68 69 6e 0a 2a 2a 20 74 6f 70 2d 6c   within.** top-l
35650 65 76 65 6c 20 61 70 70 6c 69 63 61 74 69 6f 6e  evel application
35660 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   code..**.** The
35670 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
35680 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  may attempt to c
35690 6f 6e 76 65 72 74 20 74 68 65 20 64 61 74 61 74  onvert the datat
356a0 79 70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ype of the resul
356b0 74 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78 61 6d 70  t..** ^For examp
356c0 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
356d0 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
356e0 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
356f0 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
35700 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
35710 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
35720 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
35730 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
35740 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
35750 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
35760 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77  y.  ^(The follow
35770 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
35780 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
35790 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70  s.** that are ap
357a0 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
357b0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
357c0 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
357d0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
357e0 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
357f0 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
35800 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
35810 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
35820 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
35830 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
35840 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
35850 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
35860 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
35870 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
35880 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
35890 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
358a0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
358b0 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
358c0 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
358d0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
358e0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
358f0 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20  esult is a NULL 
35900 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
35910 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
35920 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
35930 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
35940 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
35950 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
35960 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
35970 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
35980 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
35990 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
359a0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
359b0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
359c0 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
359d0 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
359e0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
359f0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
35a00 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
35a10 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
35a20 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
35a30 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
35a40 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
35a50 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
35a60 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
35a70 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
35a80 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a  [CAST] to BLOB.*
35a90 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
35aa0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
35ab0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
35ac0 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
35ad0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
35ae0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
35af0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41  d> [CAST] to REA
35b00 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  L.** <tr><td>  T
35b10 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
35b20 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
35b30 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
35b40 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
35b50 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
35b60 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
35b70 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
35b80 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
35b90 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
35ba0 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
35bb0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
35bc0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
35bd0 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
35be0 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
35bf0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
35c00 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
35c10 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
35c20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
35c30 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
35c40 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
35c50 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
35c60 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
35c70 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
35c80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
35c90 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
35ca0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
35cb0 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
35cc0 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
35cd0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
35ce0 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
35cf0 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
35d00 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
35d10 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
35d20 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
35d30 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
35d40 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
35d50 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
35d60 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
35d70 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
35d80 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
35d90 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
35da0 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
35db0 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
35dc0 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
35dd0 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
35de0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
35df0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
35e00 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
35e10 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
35e20 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
35e30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
35e40 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
35e50 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
35e60 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
35e70 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
35e80 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
35e90 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
35ea0 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
35eb0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
35ec0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
35ed0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
35ee0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
35ef0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
35f00 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
35f10 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
35f20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
35f30 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
35f40 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
35f50 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
35f60 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
35f70 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
35f80 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
35f90 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
35fa0 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
35fb0 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
35fc0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
35fd0 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
35fe0 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
35ff0 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c  r references wil
36000 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
36010 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
36020 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
36030 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
36040 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
36050 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
36060 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
36070 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
36080 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
36090 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
360a0 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
360b0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ted..**.** The s
360c0 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20  afest policy is 
360d0 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
360e0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
360f0 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
36100 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
36110 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
36120 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
36130 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
36140 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
36150 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
36160 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
36170 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
36180 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
36190 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
361a0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
361b0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
361c0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
361d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
361e0 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
361f0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
36200 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
36210 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
36220 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
36230 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
36240 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
36250 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
36260 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
36270 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
36280 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
36290 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
362a0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
362b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
362c0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
362d0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
362e0 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
362f0 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
36300 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
36310 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
36320 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
36330 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
36340 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
36350 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
36360 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
36370 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
36380 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
36390 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
363a0 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
363b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
363c0 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
363d0 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
363e0 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
363f0 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
36400 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
36410 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
36420 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
36430 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
36440 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
36450 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
36460 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
36470 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
36480 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
36490 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
364a0 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
364b0 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
364c0 69 63 61 6c 6c 79 2e 20 20 44 6f 20 6e 6f 74 20  ically.  Do not 
364d0 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
364e0 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  s returned.** fr
364f0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
36500 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
36510 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
36520 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
36530 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
36540 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
36550 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
36560 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
36570 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
36580 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
36590 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
365a0 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
365b0 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
365c0 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
365d0 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
365e0 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
365f0 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
36600 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
36610 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
36620 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
36630 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
36640 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
36650 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
36660 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
36670 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
36680 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
36690 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
366a0 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
366b0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
366c0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
366d0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
366e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
366f0 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
36700 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
36710 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
36720 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36730 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
36740 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
36750 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
36760 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
36770 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
36780 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
36790 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
367a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
367b0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
367c0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
367d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
367e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
367f0 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
36800 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
36810 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36820 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
36830 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
36840 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
36850 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
36860 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
36870 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
36880 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c  _column_type(sql
36890 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
368a0 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
368b0 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
368c0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
368d0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44  ment Object.** D
368e0 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  ESTRUCTOR: sqlit
368f0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
36900 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
36910 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
36920 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
36930 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
36940 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
36950 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
36960 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
36970 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
36980 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
36990 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
369a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
369b0 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
369c0 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
369d0 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
369e0 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
369f0 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
36a00 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
36a10 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
36a20 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
36a30 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
36a40 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
36a50 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
36a60 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
36a70 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
36a80 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
36a90 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
36aa0 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
36ab0 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
36ac0 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
36ad0 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
36ae0 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
36af0 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
36b00 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
36b10 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
36b20 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
36b30 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
36b40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
36b50 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
36b60 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
36b70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
36b80 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
36b90 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
36ba0 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
36bb0 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
36bc0 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
36bd0 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
36be0 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
36bf0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
36c00 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
36c10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
36c20 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
36c30 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
36c40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
36c50 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
36c60 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
36c70 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
36c80 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
36c90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
36ca0 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
36cb0 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
36cc0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
36cd0 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
36ce0 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
36cf0 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
36d00 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
36d10 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
36d20 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
36d30 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
36d40 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
36d50 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
36d60 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
36d70 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
36d80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
36d90 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
36da0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
36db0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
36dc0 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
36dd0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
36de0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
36df0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68  e3_stmt.**.** Th
36e00 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  e sqlite3_reset(
36e10 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
36e20 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20  lled to reset a 
36e30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
36e40 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62  ent].** object b
36e50 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
36e60 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20  al state, ready 
36e70 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65  to be re-execute
36e80 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73  d..** ^Any SQL s
36e90 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c  tatement variabl
36ea0 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75  es that had valu
36eb0 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d  es bound to them
36ec0 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73   using.** the [s
36ed0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
36ee0 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
36ef0 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20  *() API] retain 
36f00 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a  their values..**
36f10 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c   Use [sqlite3_cl
36f20 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20  ear_bindings()] 
36f30 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e  to reset the bin
36f40 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dings..**.** ^Th
36f50 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
36f60 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
36f70 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61  esets the [prepa
36f80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
36f90 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20  .** back to the 
36fa0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73  beginning of its
36fb0 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20   program..**.** 
36fc0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
36fd0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
36fe0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
36ff0 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
37000 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
37010 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
37020 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _ROW] or [SQLITE
37030 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66  _DONE],.** or if
37040 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
37050 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
37060 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
37070 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73  on S,.** then [s
37080 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
37090 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
370a0 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  _OK]..**.** ^If 
370b0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
370c0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
370d0 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
370e0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
370f0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69  tatement] S indi
37100 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20  cated an error, 
37110 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  then.** [sqlite3
37120 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
37130 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
37140 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
37150 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
37160 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
37170 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
37180 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
37190 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71  es.** of any [sq
371a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
371b0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65  bindings] on the
371c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
371d0 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20  ment] S..*/.int 
371e0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
371f0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
37200 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
37210 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
37220 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
37230 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
37240 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
37250 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
37260 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
37270 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37280 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
37290 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
372a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
372b0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
372c0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
372d0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  te3.**.** ^These
372e0 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
372f0 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
37300 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
37310 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
37320 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
37330 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
37340 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
37350 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
37360 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
37370 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
37380 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
37390 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
373a0 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74   differences bet
373b0 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f  ween.** these ro
373c0 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74  utines are the t
373d0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70  ext encoding exp
373e0 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65  ected for.** the
373f0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
37400 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r (the name of t
37410 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e  he function bein
37420 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e  g created).** an
37430 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  d the presence o
37440 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64  r absence of a d
37450 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
37460 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70  ck for.** the ap
37470 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
37480 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
37490 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
374a0 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
374b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
374c0 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
374d0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
374e0 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49  to be added.  ^I
374f0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
37500 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
37510 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
37520 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20  connection then 
37530 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
37540 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
37550 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a  s must be added.
37560 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ** to each datab
37570 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
37580 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
37590 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
375a0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
375b0 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
375c0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
375d0 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
375e0 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67  ined.  ^The leng
375f0 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
37600 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
37610 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d   bytes in a UTF-
37620 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74  8.** representat
37630 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  ion, exclusive o
37640 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  f the zero-termi
37650 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68  nator.  ^Note th
37660 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c  at the name.** l
37670 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
37680 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e  n UTF-8 bytes, n
37690 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f  ot characters no
376a0 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20  r UTF-16 bytes. 
376b0 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70   .** ^Any attemp
376c0 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
376d0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
376e0 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
376f0 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
37700 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e  ITE_MISUSE] bein
37710 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
37720 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72  * ^The third par
37730 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
37740 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
37750 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
37760 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
37770 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
37780 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69  e takes. ^If thi
37790 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d  s parameter is -
377a0 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
377b0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
377c0 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
377d0 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
377e0 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65  arguments betwee
377f0 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69  n 0 and the limi
37800 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c  t.** set by [sql
37810 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
37820 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
37830 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68  ON_ARG]).  If th
37840 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
37850 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61  eter is less tha
37860 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
37870 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68  than 127 then th
37880 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a  e behavior is.**
37890 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
378a0 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
378b0 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
378c0 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
378d0 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
378e0 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
378f0 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
37900 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
37910 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
37920 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  rs.  The applica
37930 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20  tion should set 
37940 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74  this parameter t
37950 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  o.** [SQLITE_UTF
37960 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e  16LE] if the fun
37970 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
37980 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a  tion invokes .**
37990 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
379a0 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61  text16le()] on a
379b0 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c  n input, or [SQL
379c0 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20  ITE_UTF16BE] if 
379d0 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
379e0 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73  ation invokes [s
379f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
37a00 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69  t16be()] on an i
37a10 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c  nput, or.** [SQL
37a20 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73  ITE_UTF16] if [s
37a30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
37a40 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  t16()] is used, 
37a50 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  or [SQLITE_UTF8]
37a60 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20  .** otherwise.  
37a70 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75  ^The same SQL fu
37a80 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
37a90 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c  gistered multipl
37aa0 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a  e times using.**
37ab0 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65   different prefe
37ac0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
37ad0 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72  ngs, with differ
37ae0 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
37af0 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ons for.** each 
37b00 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68  encoding..** ^Wh
37b10 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
37b20 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
37b30 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
37b40 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
37b50 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
37b60 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
37b70 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
37b80 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
37b90 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
37ba0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
37bb0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f   parameter may o
37bc0 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65  ptionally be ORe
37bd0 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
37be0 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a  ETERMINISTIC].**
37bf0 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20   to signal that 
37c00 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  the function wil
37c10 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
37c20 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20  the same result 
37c30 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  given.** the sam
37c40 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20  e inputs within 
37c50 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
37c60 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51  tement.  Most SQ
37c70 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a  L functions are.
37c80 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  ** deterministic
37c90 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20  .  The built-in 
37ca0 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66  [random()] SQL f
37cb0 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78  unction is an ex
37cc0 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75  ample of a.** fu
37cd0 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e  nction that is n
37ce0 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  ot deterministic
37cf0 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75  .  The SQLite qu
37d00 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61  ery planner is a
37d10 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72  ble to.** perfor
37d20 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74  m additional opt
37d30 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65  imizations on de
37d40 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63  terministic func
37d50 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a  tions, so use.**
37d60 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
37d70 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66  DETERMINISTIC] f
37d80 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  lag is recommend
37d90 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c  ed where possibl
37da0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  e..**.** ^(The f
37db0 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
37dc0 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
37dd0 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
37de0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
37df0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
37e00 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
37e10 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
37e20 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
37e30 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a  er_data()].)^.**
37e40 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20  .** ^The sixth, 
37e50 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68  seventh and eigh
37e60 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78  th parameters, x
37e70 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20  Func, xStep and 
37e80 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70  xFinal, are.** p
37e90 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e  ointers to C-lan
37ea0 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20  guage functions 
37eb0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
37ec0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
37ed0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e  or.** aggregate.
37ee0 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66   ^A scalar SQL f
37ef0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
37f00 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
37f10 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a  on of the xFunc.
37f20 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  ** callback only
37f30 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  ; NULL pointers 
37f40 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
37f50 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20  s the xStep and 
37f60 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65  xFinal.** parame
37f70 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67  ters. ^An aggreg
37f80 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
37f90 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
37fa0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78  lementation of x
37fb0 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
37fc0 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e  al and NULL poin
37fd0 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73  ter must be pass
37fe0 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54  ed for xFunc. ^T
37ff0 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
38000 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
38010 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
38020 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69  e, pass NULL poi
38030 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68  nters for all th
38040 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ree function.** 
38050 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a  callbacks..**.**
38060 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20   ^(If the ninth 
38070 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
38080 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
38090 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  tion_v2() is not
380a0 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69   NULL,.** then i
380b0 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20  t is destructor 
380c0 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
380d0 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
380e0 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75  . .** The destru
380f0 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20  ctor is invoked 
38100 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  when the functio
38110 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69  n is deleted, ei
38120 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a  ther by being.**
38130 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77   overloaded or w
38140 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
38150 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
38160 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65  es.)^.** ^The de
38170 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f  structor is also
38180 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20   invoked if the 
38190 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
381a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
381b0 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a  on_v2() fails..*
381c0 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74  * ^When the dest
381d0 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
381e0 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72  of the tenth par
381f0 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65  ameter is invoke
38200 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73  d, it.** is pass
38210 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  ed a single argu
38220 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
38230 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c  copy of the appl
38240 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a  ication data .**
38250 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77   pointer which w
38260 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72  as the fifth par
38270 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
38280 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
38290 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49  n_v2()..**.** ^I
382a0 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  t is permitted t
382b0 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69  o register multi
382c0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
382d0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ons of the same.
382e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74  ** functions wit
382f0 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
38300 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20  but with either 
38310 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72  differing number
38320 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  s of.** argument
38330 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70  s or differing p
38340 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
38350 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74  codings.  ^SQLit
38360 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
38370 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
38380 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65   that most close
38390 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
383a0 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
383b0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
383c0 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e  is used.  ^A fun
383d0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
383e0 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d  tion with a non-
383f0 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67  negative.** nArg
38400 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
38410 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61  better match tha
38420 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  n a function imp
38430 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
38440 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e  .** a negative n
38450 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  Arg.  ^A functio
38460 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
38470 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
38480 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
38490 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
384a0 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
384b0 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
384c0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
384d0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
384e0 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
384f0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
38500 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
38510 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
38520 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
38530 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
38540 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
38550 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
38560 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
38570 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
38580 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
38590 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
385a0 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69  ^Built-in functi
385b0 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c  ons may be overl
385c0 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70  oaded by new app
385d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
385e0 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
385f0 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  * ^An applicatio
38600 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
38610 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  on is permitted 
38620 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a  to call other.**
38630 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
38640 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75  es.  However, su
38650 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f  ch calls must no
38660 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64  t.** close the d
38670 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38680 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20  on nor finalize 
38690 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65  or reset the pre
386a0 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
386b0 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  nt in which the 
386c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
386d0 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ing..*/.int sqli
386e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
386f0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
38700 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
38710 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
38720 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
38730 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
38740 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
38750 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69