/ Hex Artifact Content
Login

Artifact 45150a75c20ad6f9d914cd6e59caf36453206b0f824d514f194b56236f2d63d7:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c  ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a  ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66  .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53  _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f   file.  ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72  us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20  s might include 
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70  nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76  lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65  erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20  atch the macros 
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72  in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72  , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69  e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d  cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68  piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20  ing library and 
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a  header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28  <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51  ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65  ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30  ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c  BER].  ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20  rocessor macro. 
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74   Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73  e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f  ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67  py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74  amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61  he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68  racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20  e hash might be 
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b  different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1e00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1e10: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1e20: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1e30: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1e40: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1e50: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1e60: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1e70: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1e80: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1e90: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1ea0: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1eb0: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1ec0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1ed0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1ee0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1ef0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1f00: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1f10: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1f20: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1f30: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1f40: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1f50: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1f60: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1f70: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1f80: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1f90: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1fa0: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1fb0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1fc0: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1fd0: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1fe0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1ff0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
2000: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
2010: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
2020: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
2030: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
2040: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
2050: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
2060: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
2070: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
2080: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
2090: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
20a0: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
20b0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
20c0: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
20d0: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
20e0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
20f0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
2100: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
2110: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
2120: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
2130: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2140: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2150: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2160: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2170: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
2180: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
2190: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
21a0: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
21b0: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
21c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
21d0: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
21e0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
21f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2200: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
2210: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
2220: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
2230: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2240: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2250: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2260: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
2290: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
22a0: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
22b0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
22c0: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
22d0: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
22e0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
22f0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
2300: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
2310: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
2320: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
2330: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2340: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2350: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2360: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2370: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
2380: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
2390: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
23a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
23b0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
23c0: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
23d0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
23e0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
23f0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
2400: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
2410: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
2420: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2430: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2440: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2450: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2460: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2470: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2480: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2490: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
24a0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
24b0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
24c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
24d0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
24e0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
24f0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
2500: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2510: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
2520: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2530: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2540: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2550: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2560: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2570: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2580: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2590: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
25a0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
25b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
25c0: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
25d0: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
25e0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
25f0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
2600: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
2610: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
2620: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
2630: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2640: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2650: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2660: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2670: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2680: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2690: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
26a0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
26b0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
26c0: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
26d0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
26e0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
26f0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
2700: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
2710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2730: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2740: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2750: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2760: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2770: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2780: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2790: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
27a0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
27b0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
27c0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
27d0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
27e0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
27f0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
2800: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2810: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
2820: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
2830: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2840: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2850: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2860: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2870: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2880: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2890: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
28a0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
28b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
28c0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
28d0: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
28e0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
28f0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
2900: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
2910: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2920: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
2930: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2940: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2950: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2960: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2970: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2980: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2990: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
29a0: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
29b0: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
29c0: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
29d0: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
29e0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
29f0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
2a00: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2a10: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2a20: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
2a30: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2a40: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2a50: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2a60: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2a70: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2a80: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2a90: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2aa0: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45  ;.# ifdef SQLITE
2ab0: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20  _UINT64_TYPE.   
2ac0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2ad0: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  UINT64_TYPE sqli
2ae0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73  te_uint64;.# els
2af0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20  e  .    typedef 
2b00: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2b20: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69  e_uint64;.# endi
2b30: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  f.#elif defined(
2b40: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2b50: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2b60: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2b70: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2b80: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2b90: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2ba0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2bb0: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2bc0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2bd0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2be0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2bf0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2c00: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2c10: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2c30: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2c40: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2c50: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2c60: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2c70: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2c80: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2c90: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2ca0: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2cb0: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2cc0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2cd0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2ce0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2cf0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2d00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2d10: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2d20: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2d30: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2d40: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2d50: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2d60: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2d70: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2d80: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2d90: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2da0: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2db0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2dc0: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2dd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2de0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2df0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2e00: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2e10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2e20: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2e30: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2e40: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2e50: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2e60: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2e80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e90: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2ea0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2eb0: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2ec0: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ed0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2ee0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2ef0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2f00: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2f10: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2f20: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2f30: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2f40: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2f50: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2f60: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2f70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2f80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2f90: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2fa0: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2fb0: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2fc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fd0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2fe0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2ff0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
3000: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
3010: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
3020: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
3030: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
3040: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
3050: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
3060: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
3070: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
3080: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
3090: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
30a0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
30b0: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
30c0: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
30d0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
30e0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
30f0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
3100: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
3110: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
3120: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
3130: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3140: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3150: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
3160: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3170: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3180: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3190: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
31a0: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
31b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
31c0: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
31d0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
31e0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31f0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
3200: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
3210: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
3220: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
3230: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3240: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3250: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3260: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3270: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3280: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3290: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
32a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32b0: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
32c0: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
32d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
32e0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
32f0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
3300: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
3310: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3320: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3330: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3340: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3350: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3360: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3370: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3380: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3390: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
33a0: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
33b0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
33c0: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
33d0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
33e0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
33f0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3400: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3410: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3420: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3440: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3450: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3460: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3470: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3480: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3490: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
34a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
34b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
34c0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
34d0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
34e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
34f0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3500: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3510: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3520: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3530: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3540: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3550: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3560: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3570: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3580: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3590: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35a0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
35b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
35c0: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
35d0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
35e0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
35f0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
3600: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
3610: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
3620: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3630: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3640: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3650: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3660: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3670: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3680: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3690: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
36a0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
36b0: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
36c0: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
36d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
36e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
36f0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
3700: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
3710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
3720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
3730: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3740: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3750: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
3760: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
3770: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
3780: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
3790: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
37a0: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
37b0: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
37c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
37e0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
37f0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
3800: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
3810: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
3820: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
3830: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
3840: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
3850: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
3860: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3870: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
3880: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
3890: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
38a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
38b0: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
38c0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
38d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
38e0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
38f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
3900: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
3910: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
3920: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
3930: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3940: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3950: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3960: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
3970: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3980: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
3990: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
39a0: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
39b0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
39c0: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
39d0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
39e0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
39f0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
3a00: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
3a10: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
3a20: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
3a30: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3a40: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
3a50: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
3a60: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3a70: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3a80: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
3a90: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3aa0: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3ab0: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3ac0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3ad0: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
3ae0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3af0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3b00: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
3b10: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
3b20: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
3b30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3b40: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
3b50: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3b60: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
3b70: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
3b90: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3ba0: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3bb0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3bc0: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3bd0: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3be0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3bf0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3c00: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3c10: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3c20: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3c30: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3c40: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3c50: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3c60: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3c70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3c90: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3ca0: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3cb0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3cc0: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3cd0: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3ce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3cf0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3d00: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3d10: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3d20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3d30: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3d40: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3d50: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3d60: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3d70: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3d80: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3d90: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3da0: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3db0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3dc0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3dd0: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3de0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3df0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3e00: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3e10: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3e20: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3e30: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3e40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3e60: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3e70: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e80: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3e90: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3ea0: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3eb0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3ec0: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3ed0: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ee0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3ef0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3f00: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3f10: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3f20: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3f30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3f40: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3f50: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3f60: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3f70: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3f80: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3f90: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3fa0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3fb0: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3fc0: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3fd0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3fe0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3ff0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
4000: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
4010: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
4020: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
4030: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
4040: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
4050: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
4060: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
4070: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
4080: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
4090: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
40a0: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
40b0: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
40c0: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
40d0: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
40e0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
40f0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
4100: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
4110: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
4120: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
4130: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
4140: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4150: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
4160: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
4170: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
4180: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
4190: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
41a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
41b0: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
41c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
41d0: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
41e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
41f0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
4200: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
4210: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4220: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
4230: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4240: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4250: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4260: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4270: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
4280: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
4290: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
42a0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
42b0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
42c0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
42d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
42e0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
42f0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
4300: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4310: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4330: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4340: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4350: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4370: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4380: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4390: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
43a0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
43b0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
43c0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
43d0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
43e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4400: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4410: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4420: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4430: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4450: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4460: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4470: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4480: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4490: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
44a0: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
44b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
44c0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
44d0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
44e0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
44f0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
4500: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4510: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4520: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4530: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4540: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4550: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4560: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4570: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4580: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4590: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
45a0: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
45b0: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
45c0: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
45d0: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
45e0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
45f0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4610: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
4620: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72  /* Generic error
4630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4640: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4650: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4660: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4670: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4680: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4690: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
46a0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
46b0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
46c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
46d0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
46e0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
46f0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
4700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4710: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
4720: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4730: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4760: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4770: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4780: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4790: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
47a0: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
47b0: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
47c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
47d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
47e0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
47f0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
4800: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
4810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4820: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4830: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4840: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4850: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4870: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4880: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4890: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
48a0: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
48b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
48c0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
48d0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
48e0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
48f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4900: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
4910: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
4920: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4930: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4940: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4950: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4960: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4970: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4980: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4990: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
49a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
49b0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
49c0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
49d0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
49e0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
49f0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
4a00: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
4a10: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
4a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4a30: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4a40: 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20 6f  * Internal use o
4a50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
4a60: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4a70: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4a80: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4a90: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4aa0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4ab0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4ac0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
4ad0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
4ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4af0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4b00: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4b10: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4b20: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4b30: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4b40: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4b50: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4b60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b70: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4b80: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4b90: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bb0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4bc0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4bd0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4be0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4c00: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4c10: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4c20: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4c30: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4c40: 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 20      24   /* Not 
4c50: 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
4c60: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4c70: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4c80: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4c90: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4ca0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4cb0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4cc0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4cd0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
4ce0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
4cf0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
4d10: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4d20: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4d30: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4d50: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4d60: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4d70: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4d90: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4da0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4db0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4dc0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4dd0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4de0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4df0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4e00: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4e10: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4e20: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4e30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4e40: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4e50: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4e60: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4e70: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4e80: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4e90: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4ea0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4eb0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ec0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4ed0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4ee0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4ef0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4f00: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4f10: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4f20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f30: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4f40: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4f50: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4f60: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4f70: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4f80: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4f90: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4fa0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4fb0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4fc0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4fd0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4fe0: 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33  .3.8 [dateof:3.3
4ff0: 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72  .8].** and later
5000: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
5010: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
5020: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
5030: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
5040: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
5050: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
5060: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b   errors. These [
5070: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
5080: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c  codes] are enabl
5090: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
50a0: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
50b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
50c0: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
50d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
50e0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
50f0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68  ()] API.  Or, th
5100: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20  e extended code 
5110: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20  for.** the most 
5120: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e  recent error can
5130: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69   be obtained usi
5140: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
5150: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
5160: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
5170: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53 53  QLITE_ERROR_MISS
5180: 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28 53  ING_COLLSEQ   (S
5190: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 31  QLITE_ERROR | (1
51a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
51b0: 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52 59  LITE_ERROR_RETRY
51c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
51d0: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32 3c  LITE_ERROR | (2<
51e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
51f0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
5200: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5210: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5220: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5230: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
5240: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
5260: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5270: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5280: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
52a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52b0: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
52c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52d0: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
52e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52f0: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5300: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5310: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5330: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
5340: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5350: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5370: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5390: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
53a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53b0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
53c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53d0: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
53f0: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5400: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5410: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5470: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5490: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54b0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54d0: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54f0: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5510: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5530: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5540: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
5550: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
5560: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5570: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5580: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5590: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
55a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55b0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
55c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55d0: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
55e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55f0: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5600: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5610: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5620: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5630: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5640: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5650: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
5660: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5670: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5680: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5690: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
56a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56b0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
56c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56d0: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
56e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56f0: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5700: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5710: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5720: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5730: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5740: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5750: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5760: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5770: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5780: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5790: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
57a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57b0: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
57c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57d0: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
57e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57f0: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5800: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5810: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5820: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5830: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
5840: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5850: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
5860: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5870: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
5880: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5890: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
58a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58b0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
58c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58d0: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
58e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58f0: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20  _BEGIN_ATOMIC   
5900: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5910: 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66   | (29<<8)).#def
5920: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5930: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20  _COMMIT_ATOMIC  
5940: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5950: 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66   | (30<<8)).#def
5960: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5970: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
5980: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5990: 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66   | (31<<8)).#def
59a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
59b0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
59c0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
59d0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
59e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
59f0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5a00: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5a10: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5a30: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5a40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5a50: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5a60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5a70: 53 59 5f 44 45 41 44 4c 4f 43 4b 20 20 20 20 20  SY_DEADLOCK     
5a80: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5a90: 53 59 20 20 20 7c 20 20 28 33 3c 3c 38 29 29 0a  SY   |  (3<<8)).
5aa0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5ab0: 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49  ANTOPEN_NOTEMPDI
5ac0: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5ad0: 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29  ANTOPEN | (1<<8)
5ae0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5af0: 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20  _CANTOPEN_ISDIR 
5b00: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5b10: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c  _CANTOPEN | (2<<
5b20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5b30: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c  TE_CANTOPEN_FULL
5b40: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5b50: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33  TE_CANTOPEN | (3
5b60: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5b70: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f  LITE_CANTOPEN_CO
5b80: 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51  NVPATH       (SQ
5b90: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5ba0: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5bb0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56  SQLITE_CORRUPT_V
5bc0: 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28  TAB            (
5bd0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c  SQLITE_CORRUPT |
5be0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5bf0: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
5c00: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5c10: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
5c20: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5c30: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5c40: 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20  LY_CANTLOCK     
5c50: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5c60: 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  LY | (2<<8)).#de
5c70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5c80: 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  ONLY_ROLLBACK   
5c90: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5ca0: 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23  ONLY | (3<<8)).#
5cb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
5cc0: 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20  ADONLY_DBMOVED  
5cd0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
5ce0: 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29  ADONLY | (4<<8))
5cf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d00: 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49 4e 49  READONLY_CANTINI
5d10: 54 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  T       (SQLITE_
5d20: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c 3c 38  READONLY | (5<<8
5d30: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d40: 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52 45 43  E_READONLY_DIREC
5d50: 54 4f 52 59 20 20 20 20 20 20 28 53 51 4c 49 54  TORY      (SQLIT
5d60: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 36 3c  E_READONLY | (6<
5d70: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5d80: 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41  ITE_ABORT_ROLLBA
5d90: 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  CK          (SQL
5da0: 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c  ITE_ABORT | (2<<
5db0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5dc0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48  TE_CONSTRAINT_CH
5dd0: 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49  ECK        (SQLI
5de0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5df0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5e00: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5e10: 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28  T_COMMITHOOK   (
5e20: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5e30: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  T | (2<<8)).#def
5e40: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5e50: 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59  RAINT_FOREIGNKEY
5e60: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5e70: 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a  RAINT | (3<<8)).
5e80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5e90: 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49  ONSTRAINT_FUNCTI
5ea0: 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  ON     (SQLITE_C
5eb0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c  ONSTRAINT | (4<<
5ec0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5ed0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f  TE_CONSTRAINT_NO
5ee0: 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49  TNULL      (SQLI
5ef0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5f00: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
5f10: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5f20: 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28  T_PRIMARYKEY   (
5f30: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5f40: 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  T | (6<<8)).#def
5f50: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5f60: 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20  RAINT_TRIGGER   
5f70: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5f80: 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a  RAINT | (7<<8)).
5f90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5fa0: 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45  ONSTRAINT_UNIQUE
5fb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5fc0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c  ONSTRAINT | (8<<
5fd0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5fe0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54  TE_CONSTRAINT_VT
5ff0: 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  AB         (SQLI
6000: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
6010: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
6020: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
6030: 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 28  T_ROWID        (
6040: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
6050: 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66  T |(10<<8)).#def
6060: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
6070: 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20  E_RECOVER_WAL   
6080: 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43     (SQLITE_NOTIC
6090: 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  E | (1<<8)).#def
60a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
60b0: 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41  E_RECOVER_ROLLBA
60c0: 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43  CK (SQLITE_NOTIC
60d0: 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  E | (2<<8)).#def
60e0: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49  ine SQLITE_WARNI
60f0: 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20  NG_AUTOINDEX    
6100: 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49     (SQLITE_WARNI
6110: 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NG | (1<<8)).#de
6120: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
6130: 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20 20  _USER           
6140: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48      (SQLITE_AUTH
6150: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
6160: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41  ne SQLITE_OK_LOA
6170: 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20  D_PERMANENTLY   
6180: 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28    (SQLITE_OK | (
6190: 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  1<<8))../*.** CA
61a0: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f  PI3REF: Flags Fo
61b0: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72  r File Open Oper
61c0: 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ations.**.** The
61d0: 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72  se bit values ar
61e0: 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
61f0: 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64  se in the.** 3rd
6200: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
6210: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
6220: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
6230: 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74  and.** in the 4t
6240: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
6250: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
6260: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a  xOpen] method..*
6270: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6280: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20  _OPEN_READONLY  
6290: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
62a0: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  1  /* Ok for sql
62b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
62c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
62d0: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
62e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
62f0: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  2  /* Ok for sql
6300: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6310: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6320: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20  _OPEN_CREATE    
6330: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6340: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  4  /* Ok for sql
6350: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6360: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6370: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
6380: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30  OSE    0x0000000
6390: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  8  /* VFS only *
63a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
63b0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
63c0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
63d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
63e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
63f0: 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20  _OPEN_AUTOPROXY 
6400: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
6410: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6420: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6430: 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20  _OPEN_URI       
6440: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
6450: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6460: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6470: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6480: 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20  _OPEN_MEMORY    
6490: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
64a0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
64b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
64c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
64d0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20  _OPEN_MAIN_DB   
64e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
64f0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6500: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6510: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20  _OPEN_TEMP_DB   
6520: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6530: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6540: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6550: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
6560: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30  DB     0x0000040
6570: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6580: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6590: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
65a0: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30  AL     0x0000080
65b0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
65c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
65d0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
65e0: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30  AL     0x0000100
65f0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6600: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6610: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
6620: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
6630: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6640: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6650: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
6660: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30  RNAL   0x0000400
6670: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6680: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6690: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20  _OPEN_NOMUTEX   
66a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30         0x0000800
66b0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
66c0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
66d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
66e0: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20  _OPEN_FULLMUTEX 
66f0: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30         0x0001000
6700: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6710: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6720: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6730: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
6740: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30  E      0x0002000
6750: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6760: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6770: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6780: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
6790: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30  HE     0x0004000
67a0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
67b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
67c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
67d0: 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20  _OPEN_WAL       
67e0: 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30         0x0008000
67f0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6800: 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20  /../* Reserved: 
6810: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6820: 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30          0x00F000
6830: 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00 */../*.** CAP
6840: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
6850: 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a  aracteristics.**
6860: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43  .** The xDeviceC
6870: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
6880: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71  ethod of the [sq
6890: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
68a0: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75  ].** object retu
68b0: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77  rns an integer w
68c0: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72  hich is a vector
68d0: 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74   of these.** bit
68e0: 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69   values expressi
68f0: 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72  ng I/O character
6900: 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61  istics of the ma
6910: 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65  ss storage.** de
6920: 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20  vice that holds 
6930: 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68  the file that th
6940: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6950: 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73  thods].** refers
6960: 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53   to..**.** The S
6970: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6980: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
6990: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
69a0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
69b0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
69c0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
69d0: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
69e0: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
69f0: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
6a00: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
6a10: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
6a20: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
6a30: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
6a40: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
6a50: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
6a60: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6a70: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6a80: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
6a90: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
6aa0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
6ab0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
6ac0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
6ad0: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
6ae0: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
6af0: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
6b00: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
6b10: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
6b20: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
6b30: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6b40: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6b50: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
6b60: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
6b70: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
6b80: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
6b90: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
6ba0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6bb0: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
6bc0: 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79  ERWRITE property
6bd0: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61   means that.** a
6be0: 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c  fter reboot foll
6bf0: 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72  owing a crash or
6c00: 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65   power loss, the
6c10: 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61   only bytes in a
6c20: 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65  .** file that we
6c30: 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68  re written at th
6c40: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65  e application le
6c50: 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63  vel might have c
6c60: 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68  hanged.** and th
6c70: 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65  at adjacent byte
6c80: 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69  s, even bytes wi
6c90: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65  thin the same se
6ca0: 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72  ctor are.** guar
6cb0: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63  anteed to be unc
6cc0: 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c  hanged.  The SQL
6cd0: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
6ce0: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a  TABLE_WHEN_OPEN.
6cf0: 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65  ** flag indicate
6d00: 73 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61  s that a file ca
6d10: 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20  nnot be deleted 
6d20: 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a  when open.  The.
6d30: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ** SQLITE_IOCAP_
6d40: 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69  IMMUTABLE flag i
6d50: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
6d60: 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20  e file is on.** 
6d70: 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20  read-only media 
6d80: 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  and cannot be ch
6d90: 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72  anged even by pr
6da0: 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20  ocesses with.** 
6db0: 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65  elevated privile
6dc0: 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  ges..**.** The S
6dd0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43  QLITE_IOCAP_BATC
6de0: 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  H_ATOMIC propert
6df0: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  y means that the
6e00: 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 66   underlying.** f
6e10: 69 6c 65 73 79 73 74 65 6d 20 73 75 70 70 6f 72  ilesystem suppor
6e20: 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69 70 6c  ts doing multipl
6e30: 65 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f  e write operatio
6e40: 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20 77 68  ns atomically wh
6e50: 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72 69 74  en those.** writ
6e60: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  e operations are
6e70: 20 62 72 61 63 6b 65 74 65 64 20 62 79 20 5b 53   bracketed by [S
6e80: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
6e90: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  N_ATOMIC_WRITE] 
6ea0: 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  and.** [SQLITE_F
6eb0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d  CNTL_COMMIT_ATOM
6ec0: 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a 23 64  IC_WRITE]..*/.#d
6ed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6ee0: 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20  AP_ATOMIC       
6ef0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6f00: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
6f10: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6f20: 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20  512             
6f30: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
6f40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6f50: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20  _ATOMIC1K       
6f60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6f70: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
6f80: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
6f90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6fa0: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e  x00000008.#defin
6fb0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6fc0: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20  TOMIC4K         
6fd0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
6fe0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6ff0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20  IOCAP_ATOMIC8K  
7000: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
7010: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20  0000020.#define 
7020: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7030: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20  MIC16K          
7040: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23      0x00000040.#
7050: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7060: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20  CAP_ATOMIC32K   
7070: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
7080: 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51  00080.#define SQ
7090: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
70a0: 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  C64K            
70b0: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
70c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
70d0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20  P_SAFE_APPEND   
70e0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
70f0: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
7100: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
7110: 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  IAL             
7120: 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69  0x00000400.#defi
7130: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
7140: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
7150: 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30  _OPEN  0x0000080
7160: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
7170: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
7180: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78  _OVERWRITE    0x
7190: 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65  00001000.#define
71a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d   SQLITE_IOCAP_IM
71b0: 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  MUTABLE         
71c0: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a       0x00002000.
71d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
71e0: 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d 49  OCAP_BATCH_ATOMI
71f0: 43 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  C           0x00
7200: 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  004000../*.** CA
7210: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
7220: 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a  king Levels.**.*
7230: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
7240: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
7250: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
7260: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
7270: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
7280: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
7290: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
72a0: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
72b0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
72c0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
72d0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
72e0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
72f0: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
7300: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7310: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
7320: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
7330: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
7340: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
7350: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
7360: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
7370: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
7380: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
7390: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
73a0: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
73b0: 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  ags.**.** When S
73c0: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
73d0: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
73e0: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
73f0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
7400: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
7410: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
7420: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
7430: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
7440: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
7450: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
7460: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
7470: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
7480: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
7490: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
74a0: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
74b0: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
74c0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
74d0: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
74e0: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
74f0: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65   flushed. If the
7500: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
7510: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20   of the flag.** 
7520: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
7530: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d  C_NORMAL, that m
7540: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d  eans to use norm
7550: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
7560: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  tics..** If the 
7570: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
7580: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
7590: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61  C_FULL, that mea
75a0: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  ns.** to use Mac
75b0: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
75c0: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
75d0: 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44  fsync()..**.** D
75e0: 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68  o not confuse th
75f0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
7600: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
7610: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a  SYNC_FULL flags.
7620: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41  ** with the [PRA
7630: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
7640: 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41  =NORMAL and [PRA
7650: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
7660: 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67  =FULL.** setting
7670: 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f  s.  The [synchro
7680: 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74  nous pragma] det
7690: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c  ermines when cal
76a0: 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79  ls to the.** xSy
76b0: 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63  nc VFS method oc
76c0: 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20  cur and applies 
76d0: 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73  uniformly across
76e0: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a   all platforms..
76f0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  ** The SQLITE_SY
7700: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
7710: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
7720: 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68  lags determine h
7730: 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20  ow.** energetic 
7740: 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66  or rigorous or f
7750: 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63  orceful the sync
7760: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
7770: 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65  and.** only make
7780: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e   a difference on
7790: 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65   Mac OSX for the
77a0: 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20   default SQLite 
77b0: 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d  code..** (Third-
77c0: 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d  party VFS implem
77d0: 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  entations might 
77e0: 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69  also make the di
77f0: 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
7800: 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43  ween SQLITE_SYNC
7810: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
7820: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75  TE_SYNC_FULL, bu
7830: 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f  t among the.** o
7840: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73  perating systems
7850: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72   natively suppor
7860: 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f  ted by SQLite, o
7870: 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63  nly Mac OSX.** c
7880: 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64  ares about the d
7890: 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23  ifference.).*/.#
78a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
78b0: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
78c0: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
78d0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
78e0: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
78f0: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
7900: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
7910: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
7920: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
7930: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
7940: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  File Handle.**.*
7950: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
7960: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
7970: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
7980: 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73  le in the .** [s
7990: 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20  qlite3_vfs | OS 
79a0: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d  interface layer]
79b0: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
79c0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d   interface.** im
79d0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
79e0: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75  ll.** want to su
79f0: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65  bclass this obje
7a00: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20  ct by appending 
7a10: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
7a20: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f  s.** for their o
7a30: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65  wn use.  The pMe
7a40: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61  thods entry is a
7a50: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
7a60: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
7a70: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68  thods] object th
7a80: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f  at defines metho
7a90: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e  ds for performin
7aa0: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69  g.** I/O operati
7ab0: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20  ons on the open 
7ac0: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  file..*/.typedef
7ad0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7ae0: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c  file sqlite3_fil
7af0: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  e;.struct sqlite
7b00: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74  3_file {.  const
7b10: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7b20: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74  io_methods *pMet
7b30: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64  hods;  /* Method
7b40: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69  s for an open fi
7b50: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  le */.};../*.** 
7b60: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
7b70: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74  erface File Virt
7b80: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  ual Methods Obje
7b90: 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  ct.**.** Every f
7ba0: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
7bb0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7bc0: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70  Open] method pop
7bd0: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
7be0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7bf0: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
7c00: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
7c10: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
7c20: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7c30: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
7c40: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
7c50: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
7c60: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
7c70: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
7c80: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
7c90: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
7ca0: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
7cb0: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
7cc0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
7cd0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
7ce0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7cf0: 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  If the [sqlite3_
7d00: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
7d10: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
7d20: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7d30: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
7d40: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
7d50: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
7d60: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
7d70: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
7d80: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
7d90: 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c  even if the [sql
7da0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7db0: 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74  reported that it
7dc0: 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a   failed.  The.**
7dd0: 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65   only way to pre
7de0: 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78  vent a call to x
7df0: 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  Close following 
7e00: 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65  a failed [sqlite
7e10: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20  3_vfs.xOpen].** 
7e20: 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  is for the [sqli
7e30: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74  te3_vfs.xOpen] t
7e40: 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  o set the sqlite
7e50: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
7e60: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55  element.** to NU
7e70: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
7e80: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
7e90: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
7ea0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
7eb0: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
7ec0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7ed0: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
7ee0: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
7ef0: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
7f00: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
7f10: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
7f20: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
7f30: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
7f40: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
7f50: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
7f60: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
7f70: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
7f80: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
7f90: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
7fa0: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
7fb0: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
7fc0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
7fd0: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
7fe0: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
7ff0: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
8000: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
8010: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
8020: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
8030: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
8040: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
8050: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
8060: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
8070: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
8080: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
8090: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
80a0: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
80b0: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
80c0: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
80d0: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
80e0: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
80f0: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
8100: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
8110: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
8120: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
8130: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
8140: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
8150: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
8160: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
8170: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
8180: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
8190: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
81a0: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
81b0: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
81c0: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
81d0: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
81e0: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
81f0: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
8200: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
8210: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
8220: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
8230: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
8240: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
8250: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
8260: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
8270: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
8280: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
8290: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
82a0: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
82b0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
82c0: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
82d0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
82e0: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
82f0: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
8300: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
8310: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
8320: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
8330: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
8340: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
8350: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
8360: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
8370: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
8380: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
8390: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
83a0: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
83b0: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
83c0: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
83d0: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
83e0: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
83f0: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
8400: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
8410: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
8420: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
8430: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
8440: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
8450: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
8460: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
8470: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
8480: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
8490: 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   [file control o
84a0: 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66  pcodes | list of
84b0: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
84c0: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
84d0: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
84e0: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
84f0: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
8500: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
8510: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
8520: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61  s.** greater tha
8530: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63  n 100 to avoid c
8540: 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69  onflicts.  VFS i
8550: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
8560: 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
8570: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
8580: 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72  ] for file contr
8590: 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20  ol opcodes that 
85a0: 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72  they do not.** r
85b0: 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20  ecognize..**.** 
85c0: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
85d0: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
85e0: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
85f0: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
8600: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
8610: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
8620: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
8630: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
8640: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
8650: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
8660: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
8670: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
8680: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
8690: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
86a0: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
86b0: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
86c0: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
86d0: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
86e0: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
86f0: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
8700: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
8710: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d  TE_IOCAP_ATOMIC]
8720: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8730: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
8740: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8750: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
8760: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8770: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
8780: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8790: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
87a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
87b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
87c0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
87d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
87e0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
87f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
8800: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
8810: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8820: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  64K].** <li> [SQ
8830: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
8840: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20  APPEND].** <li> 
8850: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45  [SQLITE_IOCAP_SE
8860: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69  QUENTIAL].** <li
8870: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8880: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
8890: 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  _OPEN].** <li> [
88a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
88b0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
88c0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
88d0: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
88e0: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
88f0: 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41  TE_IOCAP_BATCH_A
8900: 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  TOMIC].** </ul>.
8910: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
8920: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
8930: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
8940: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
8950: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
8960: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
8970: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8980: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
8990: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
89a0: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
89b0: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
89c0: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
89d0: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
89e0: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
89f0: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
8a00: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
8a10: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
8a20: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
8a30: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
8a40: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
8a50: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
8a60: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
8a70: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
8a80: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
8a90: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
8aa0: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
8ab0: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
8ac0: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
8ad0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8ae0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
8af0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
8b00: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
8b10: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
8b20: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
8b30: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
8b40: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a  to xWrite()..**.
8b50: 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65  ** If xRead() re
8b60: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45  turns SQLITE_IOE
8b70: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74  RR_SHORT_READ it
8b80: 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a   must also fill.
8b90: 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64  ** in the unread
8ba0: 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65   portions of the
8bb0: 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72   buffer with zer
8bc0: 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a  os.  A VFS that.
8bd0: 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f  ** fails to zero
8be0: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
8bf0: 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20  s might seem to 
8c00: 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a  work.  However,.
8c10: 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65  ** failure to ze
8c20: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
8c30: 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61  ads will eventua
8c40: 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64  lly lead to.** d
8c50: 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
8c60: 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
8c70: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
8c80: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
8c90: 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  _io_methods;.str
8ca0: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
8cb0: 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69  ethods {.  int i
8cc0: 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
8cd0: 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
8ce0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8cf0: 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f  *xRead)(sqlite3_
8d00: 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e  file*, void*, in
8d10: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
8d20: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
8d30: 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71  int (*xWrite)(sq
8d40: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e  lite3_file*, con
8d50: 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  st void*, int iA
8d60: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
8d70: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
8d80: 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c  (*xTruncate)(sql
8d90: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8da0: 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b  te3_int64 size);
8db0: 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28  .  int (*xSync)(
8dc0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8dd0: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74  nt flags);.  int
8de0: 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71   (*xFileSize)(sq
8df0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
8e00: 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a  ite3_int64 *pSiz
8e10: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63  e);.  int (*xLoc
8e20: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8e30: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
8e40: 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33  xUnlock)(sqlite3
8e50: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
8e60: 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65  int (*xCheckRese
8e70: 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65  rvedLock)(sqlite
8e80: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52  3_file*, int *pR
8e90: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
8ea0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71  xFileControl)(sq
8eb0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8ec0: 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29   op, void *pArg)
8ed0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f  ;.  int (*xSecto
8ee0: 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  rSize)(sqlite3_f
8ef0: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
8f00: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
8f10: 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66  stics)(sqlite3_f
8f20: 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  ile*);.  /* Meth
8f30: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
8f40: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
8f50: 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68  1 */.  int (*xSh
8f60: 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  mMap)(sqlite3_fi
8f70: 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e  le*, int iPg, in
8f80: 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69  t pgsz, int, voi
8f90: 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20  d volatile**);. 
8fa0: 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29   int (*xShmLock)
8fb0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8fc0: 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20  int offset, int 
8fd0: 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  n, int flags);. 
8fe0: 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72   void (*xShmBarr
8ff0: 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ier)(sqlite3_fil
9000: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  e*);.  int (*xSh
9010: 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f  mUnmap)(sqlite3_
9020: 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74  file*, int delet
9030: 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74  eFlag);.  /* Met
9040: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
9050: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
9060: 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46   2 */.  int (*xF
9070: 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69  etch)(sqlite3_fi
9080: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
9090: 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41  64 iOfst, int iA
90a0: 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a  mt, void **pp);.
90b0: 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68    int (*xUnfetch
90c0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
90d0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
90e0: 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a  Ofst, void *p);.
90f0: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
9100: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
9110: 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20   version 3 */.  
9120: 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65  /* Additional me
9130: 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64  thods may be add
9140: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
9150: 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  eases */.};../*.
9160: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61  ** CAPI3REF: Sta
9170: 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72  ndard File Contr
9180: 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45  ol Opcodes.** KE
9190: 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f  YWORDS: {file co
91a0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b  ntrol opcodes} {
91b0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
91c0: 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ode}.**.** These
91d0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
91e0: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
91f0: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
9200: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
9210: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
9220: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
9230: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71   and for the [sq
9240: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9250: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ol()].** interfa
9260: 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ce..**.** <ul>.*
9270: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9280: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d  CNTL_LOCKSTATE]]
9290: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
92a0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
92b0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
92c0: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
92d0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
92e0: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
92f0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
9300: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
9310: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
9320: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
9330: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
9340: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
9350: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
9360: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
9370: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
9380: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
9390: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
93a0: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
93b0: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
93c0: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
93d0: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69  t points to. Thi
93e0: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
93f0: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
9400: 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e  esting and is on
9410: 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65  ly available whe
9420: 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53  n the SQLITE_TES
9430: 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  T.** compile-tim
9440: 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  e option is used
9450: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9460: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
9470: 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  HINT]].** The [S
9480: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
9490: 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73  _HINT] opcode is
94a0: 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20   used by SQLite 
94b0: 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a  to give the VFS.
94c0: 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20  ** layer a hint 
94d0: 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65  of how large the
94e0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
94f0: 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64  ill grow to be d
9500: 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72  uring the.** cur
9510: 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  rent transaction
9520: 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
9530: 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74  not guaranteed t
9540: 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75  o be accurate bu
9550: 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e  t it.** is often
9560: 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64   close.  The und
9570: 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68  erlying VFS migh
9580: 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61  t choose to prea
9590: 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65  llocate database
95a0: 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62  .** file space b
95b0: 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e  ased on this hin
95c0: 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65  t in order to he
95d0: 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65  lp writes to the
95e0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
95f0: 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a  e run faster..**
9600: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9610: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
9620: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
9630: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
9640: 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  IZE] opcode is u
9650: 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74  sed to request t
9660: 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65  hat the VFS.** e
9670: 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63  xtends and trunc
9680: 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ates the databas
9690: 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73  e file in chunks
96a0: 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69   of a size speci
96b0: 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75  fied.** by the u
96c0: 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ser. The fourth 
96d0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
96e0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
96f0: 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20  l()] should .** 
9700: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65  point to an inte
9710: 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63  ger (type int) c
9720: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65  ontaining the ne
9730: 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20  w chunk-size to 
9740: 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e  use.** for the n
9750: 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73  ominated databas
9760: 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61  e. Allocating da
9770: 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63  tabase file spac
9780: 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68  e in large.** ch
9790: 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74  unks (say 1MB at
97a0: 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65   a time), may re
97b0: 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d  duce file-system
97c0: 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61   fragmentation a
97d0: 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65  nd.** improve pe
97e0: 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d  rformance on som
97f0: 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a  e systems..**.**
9800: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9810: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
9820: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9830: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
9840: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
9850: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
9860: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
9870: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
9880: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
9890: 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69  ted with a parti
98a0: 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a  cular database.*
98b0: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53  * connection.  S
98c0: 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f  ee also [SQLITE_
98d0: 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f  FCNTL_JOURNAL_PO
98e0: 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  INTER]..**.** <l
98f0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9900: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
9910: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9920: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
9930: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
9940: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
9950: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
9960: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
9970: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
9980: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
9990: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 69  journal file (ei
99a0: 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c  ther.** the [rol
99b0: 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f  lback journal] o
99c0: 72 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68 65  r the [write-ahe
99d0: 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70  ad log]) for a p
99e0: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
99f0: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
9a00: 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c  .  See also [SQL
9a10: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
9a20: 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  OINTER]..**.** <
9a30: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9a40: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d  L_SYNC_OMITTED]]
9a50: 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e  .** No longer in
9a60: 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e   use..**.** <li>
9a70: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
9a80: 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  YNC]].** The [SQ
9a90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d  LITE_FCNTL_SYNC]
9aa0: 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72   opcode is gener
9ab0: 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ated internally 
9ac0: 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a  by SQLite and.**
9ad0: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53   sent to the VFS
9ae0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66   immediately bef
9af0: 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65  ore the xSync me
9b00: 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
9b10: 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65  on a.** database
9b20: 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72   file descriptor
9b30: 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79  . Or, if the xSy
9b40: 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74  nc method is not
9b50: 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63   invoked .** bec
9b60: 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61  ause the user ha
9b70: 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c  s configured SQL
9b80: 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52  ite with .** [PR
9b90: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
9ba0: 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72   | PRAGMA synchr
9bb0: 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73  onous=OFF] it is
9bc0: 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63   invoked in plac
9bd0: 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79  e .** of the xSy
9be0: 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f  nc method. In mo
9bf0: 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f  st cases, the po
9c00: 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70  inter argument p
9c10: 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  assed with.** th
9c20: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  is file-control 
9c30: 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72  is NULL. However
9c40: 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73  , if the databas
9c50: 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20  e file is being 
9c60: 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72  synced.** as par
9c70: 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74  t of a multi-dat
9c80: 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68  abase commit, th
9c90: 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  e argument point
9ca0: 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69  s to a nul-termi
9cb0: 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
9cc0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74  containing the t
9cd0: 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74  ransactions mast
9ce0: 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20  er-journal file 
9cf0: 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74  name. VFSes that
9d00: 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64   .** do not need
9d10: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f   this signal sho
9d20: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
9d30: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
9d40: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a   Applications .*
9d50: 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  * should not cal
9d60: 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  l [sqlite3_file_
9d70: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
9d80: 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64  this opcode as d
9d90: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20  oing so may .** 
9da0: 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72  disrupt the oper
9db0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
9dc0: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74  cialized VFSes t
9dd0: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
9de0: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
9df0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
9e00: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a  MMIT_PHASETWO]].
9e10: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9e20: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
9e30: 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20  ETWO] opcode is 
9e40: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e  generated intern
9e50: 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a  ally by SQLite.*
9e60: 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68  * and sent to th
9e70: 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72  e VFS after a tr
9e80: 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65  ansaction has be
9e90: 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d  en committed imm
9ea0: 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20  ediately.** but 
9eb0: 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62  before the datab
9ec0: 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e  ase is unlocked.
9ed0: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e   VFSes that do n
9ee0: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  ot need this sig
9ef0: 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69  nal.** should si
9f00: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
9f10: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69  is opcode. Appli
9f20: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e  cations should n
9f30: 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  ot call.** [sqli
9f40: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9f50: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70  ()] with this op
9f60: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
9f70: 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65   may disrupt the
9f80: 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f   .** operation o
9f90: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
9fa0: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  d VFSes that do 
9fb0: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
9fc0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9fd0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
9fe0: 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20  RETRY]].** ^The 
9ff0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
a000: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70  N32_AV_RETRY] op
a010: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
a020: 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61  configure automa
a030: 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75  tic.** retry cou
a040: 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c  nts and interval
a050: 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69  s for certain di
a060: 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  sk I/O operation
a070: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e  s for the.** win
a080: 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72  dows [VFS] in or
a090: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72  der to provide r
a0a0: 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65  obustness in the
a0b0: 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20   presence of.** 
a0c0: 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72  anti-virus progr
a0d0: 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ams.  By default
a0e0: 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46  , the windows VF
a0f0: 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c  S will retry fil
a100: 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20  e read,.** file 
a110: 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20  write, and file 
a120: 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e  delete operation
a130: 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73  s up to 10 times
a140: 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a  , with a delay.*
a150: 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63  * of 25 millisec
a160: 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20  onds before the 
a170: 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20  first retry and 
a180: 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69  with the delay i
a190: 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20  ncreasing.** by 
a1a0: 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35  an additional 25
a1b0: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69   milliseconds wi
a1c0: 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65  th each subseque
a1d0: 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a  nt retry.  This.
a1e0: 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73  ** opcode allows
a1f0: 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65   these two value
a200: 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e  s (10 retries an
a210: 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  d 25 millisecond
a220: 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74  s of delay).** t
a230: 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20  o be adjusted.  
a240: 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63  The values are c
a250: 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64  hanged for all d
a260: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
a270: 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68  ons.** within th
a280: 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20  e same process. 
a290: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
a2a0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
a2b0: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a   array of two.**
a2c0: 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20   integers where 
a2d0: 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65  the first intege
a2e0: 72 20 69 73 20 74 68 65 20 6e 65 77 20 72 65 74  r is the new ret
a2f0: 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65  ry count and the
a300: 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67   second.** integ
a310: 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e  er is the delay.
a320: 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65    If either inte
a330: 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ger is negative,
a340: 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e   then the settin
a350: 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  g.** is not chan
a360: 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20  ged but instead 
a370: 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
a380: 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20  of that setting 
a390: 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e  is written.** in
a3a0: 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74  to the array ent
a3b0: 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65  ry, allowing the
a3c0: 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73   current retry s
a3d0: 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a  ettings to be.**
a3e0: 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20   interrogated.  
a3f0: 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61  The zDbName para
a400: 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64  meter is ignored
a410: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a420: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
a430: 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65  ST_WAL]].** ^The
a440: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a450: 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f  ERSIST_WAL] opco
a460: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
a470: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
a480: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41  * persistent [WA
a490: 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20  L | Write Ahead 
a4a0: 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42  Log] setting.  B
a4b0: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61  y default, the a
a4c0: 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74  uxiliary.** writ
a4d0: 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20  e ahead log and 
a4e0: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
a4f0: 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61  les used for tra
a500: 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
a510: 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69  .** are automati
a520: 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68  cally deleted wh
a530: 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f  en the latest co
a540: 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20  nnection to the 
a550: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73  database.** clos
a560: 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72  es.  Setting per
a570: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
a580: 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69   causes those fi
a590: 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61  les to persist a
a5a0: 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20  fter.** close.  
a5b0: 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66  Persisting the f
a5c0: 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77  iles is useful w
a5d0: 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73  hen other proces
a5e0: 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a  ses that do not.
a5f0: 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65  ** have write pe
a600: 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20  rmission on the 
a610: 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69  directory contai
a620: 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
a630: 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74  e file want.** t
a640: 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62  o read the datab
a650: 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65  ase file, as the
a660: 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20   WAL and shared 
a670: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73  memory files mus
a680: 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72  t exist.** in or
a690: 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61  der for the data
a6a0: 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61  base to be reada
a6b0: 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68  ble.  The fourth
a6c0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
a6d0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
a6e0: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
a6f0: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
a700: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
a710: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
a720: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
a730: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72  0 to disable per
a740: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
a750: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a760: 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41  persistent.** WA
a770: 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  L mode.  If the 
a780: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
a790: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
a7a0: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
a7b0: 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65  urrent.** WAL pe
a7c0: 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e  rsistence settin
a7d0: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
a7e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
a7f0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
a800: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a810: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
a820: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63  E_OVERWRITE] opc
a830: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
a840: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
a850: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70  ** persistent "p
a860: 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69  owersafe-overwri
a870: 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65  te" or "PSOW" se
a880: 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57  tting.  The PSOW
a890: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65   setting.** dete
a8a0: 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49  rmines the [SQLI
a8b0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
a8c0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69  FE_OVERWRITE] bi
a8d0: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76  t of the.** xDev
a8e0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
a8f0: 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20  cs methods. The 
a900: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
a910: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
a920: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
a930: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
a940: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
a950: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
a960: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
a970: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
a980: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  le zero-damage m
a990: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62  ode or 1 to enab
a9a0: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a  le zero-damage.*
a9b0: 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  * mode.  If the 
a9c0: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
a9d0: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
a9e0: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
a9f0: 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64  urrent.** zero-d
aa00: 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69  amage mode setti
aa10: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
aa20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
aa30: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
aa40: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f   [SQLITE_FCNTL_O
aa50: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
aa60: 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53   is invoked by S
aa70: 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e  QLite after open
aa80: 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74  ing.** a write t
aa90: 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e  ransaction to in
aaa0: 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c  dicate that, unl
aab0: 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64  ess it is rolled
aac0: 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a   back for some.*
aad0: 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e  * reason, the en
aae0: 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69  tire database fi
aaf0: 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77  le will be overw
ab00: 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75  ritten by the cu
ab10: 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61  rrent .** transa
ab20: 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75  ction. This is u
ab30: 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70  sed by VACUUM op
ab40: 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
ab50: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
ab60: 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20  TL_VFSNAME]].** 
ab70: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
ab80: 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f  TL_VFSNAME] opco
ab90: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  de can be used t
aba0: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d  o obtain the nam
abb0: 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46  es of.** all [VF
abc0: 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20  Ses] in the VFS 
abd0: 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65  stack.  The name
abe0: 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53  s are of all VFS
abf0: 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a   shims and the.*
ac00: 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c  * final bottom-l
ac10: 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69  evel VFS are wri
ac20: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
ac30: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a   obtained from .
ac40: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
ac50: 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65  oc()] and the re
ac60: 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69  sult is stored i
ac70: 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69  n the char* vari
ac80: 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65  able.** that the
ac90: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
aca0: 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69  r of [sqlite3_fi
acb0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f  le_control()] po
acc0: 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20  ints to..** The 
acd0: 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e  caller is respon
ace0: 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e  sible for freein
acf0: 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65  g the memory whe
ad00: 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68  n done.  As with
ad10: 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e  .** all file-con
ad20: 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68  trol actions, th
ad30: 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e  ere is no guaran
ad40: 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69  tee that this wi
ad50: 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64  ll actually.** d
ad60: 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c  o anything.  Cal
ad70: 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74  lers should init
ad80: 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a  ialize the char*
ad90: 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e   variable to a N
ada0: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ULL.** pointer i
adb0: 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65  n case this file
adc0: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20  -control is not 
add0: 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68  implemented.  Th
ade0: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a  is file-control.
adf0: 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66  ** is intended f
ae00: 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73  or diagnostic us
ae10: 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  e only..**.** <l
ae20: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ae30: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a  _VFS_POINTER]].*
ae40: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
ae50: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
ae60: 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 61  ] opcode finds a
ae70: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
ae80: 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46  top-level.** [VF
ae90: 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 69  Ses] currently i
aea0: 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61 72  n use.  ^(The ar
aeb0: 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73  gument X in.** s
aec0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
aed0: 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 43  rol(db,SQLITE_FC
aee0: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c  NTL_VFS_POINTER,
aef0: 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66  X) must be.** of
af00: 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33 5f   type "[sqlite3_
af10: 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20  vfs] **".  This 
af20: 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 74  opcodes will set
af30: 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e   *X.** to a poin
af40: 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c  ter to the top-l
af50: 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e  evel VFS.)^.** ^
af60: 57 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6d  When there are m
af70: 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69 6d  ultiple VFS shim
af80: 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c 20  s in the stack, 
af90: 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e 64  this opcode find
afa0: 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d  s the.** upper-m
afb0: 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a  ost shim only..*
afc0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
afd0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d  E_FCNTL_PRAGMA]]
afe0: 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20  .** ^Whenever a 
aff0: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
b000: 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e  nt is parsed, an
b010: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
b020: 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20  RAGMA] .** file 
b030: 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20  control is sent 
b040: 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c  to the open [sql
b050: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
b060: 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  t corresponding.
b070: 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ** to the databa
b080: 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68  se file to which
b090: 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74   the pragma stat
b0a0: 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54  ement refers. ^T
b0b0: 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  he argument.** t
b0c0: 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  o the [SQLITE_FC
b0d0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
b0e0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61   control is an a
b0f0: 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74  rray of.** point
b100: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28  ers to strings (
b110: 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68  char**) in which
b120: 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d   the second elem
b130: 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79  ent of the array
b140: 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
b150: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e  of the pragma an
b160: 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d  d the third elem
b170: 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ent is the argum
b180: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72  ent to the.** pr
b190: 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20  agma or NULL if 
b1a0: 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e  the pragma has n
b1b0: 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68  o argument.  ^Th
b1c0: 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e  e handler for an
b1d0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
b1e0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
b1f0: 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f  ontrol can optio
b200: 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66  nally make the f
b210: 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  irst element.** 
b220: 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72  of the char** ar
b230: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20  gument point to 
b240: 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  a string obtaine
b250: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
b260: 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72  mprintf()].** or
b270: 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20   the equivalent 
b280: 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20  and that string 
b290: 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20  will become the 
b2a0: 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72  result of the pr
b2b0: 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65  agma or.** the e
b2c0: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20  rror message if 
b2d0: 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73  the pragma fails
b2e0: 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51  . ^If the.** [SQ
b2f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
b300: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
b310: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
b320: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20  NOTFOUND], then 
b330: 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47  normal .** [PRAG
b340: 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63  MA] processing c
b350: 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74  ontinues.  ^If t
b360: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b370: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
b380: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
b390: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
b3a0: 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73  en the parser as
b3b0: 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
b3c0: 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65  * VFS has handle
b3d0: 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73  d the PRAGMA its
b3e0: 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73  elf and the pars
b3f0: 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e  er generates a n
b400: 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64  o-op.** prepared
b410: 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65   statement if re
b420: 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e  sult string is N
b430: 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74  ULL, or that ret
b440: 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  urns a copy.** o
b450: 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 74 72  f the result str
b460: 69 6e 67 20 69 66 20 74 68 65 20 73 74 72 69 6e  ing if the strin
b470: 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a  g is non-NULL..*
b480: 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
b490: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
b4a0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
b4b0: 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75  urns.** any resu
b4c0: 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68  lt code other th
b4d0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  an [SQLITE_OK] o
b4e0: 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  r [SQLITE_NOTFOU
b4f0: 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ND], that means.
b500: 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20  ** that the VFS 
b510: 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65  encountered an e
b520: 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c  rror while handl
b530: 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d  ing the [PRAGMA]
b540: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70   and the.** comp
b550: 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50  ilation of the P
b560: 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68  RAGMA fails with
b570: 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65   an error.  ^The
b580: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
b590: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
b5a0: 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74  ontrol occurs at
b5b0: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
b5c0: 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  f pragma stateme
b5d0: 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20  nt analysis and 
b5e0: 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65  so.** it is able
b5f0: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69   to override bui
b600: 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73  lt-in [PRAGMA] s
b610: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
b620: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b630: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
b640: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
b650: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
b660: 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  LER].** file-con
b670: 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f  trol may be invo
b680: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e  ked by SQLite on
b690: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
b6a0: 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f  le handle.** sho
b6b0: 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73  rtly after it is
b6c0: 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72   opened in order
b6d0: 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75   to provide a cu
b6e0: 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63  stom VFS with ac
b6f0: 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  cess.** to the c
b700: 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d  onnections busy-
b710: 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
b720: 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  . The argument i
b730: 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20  s of type (void 
b740: 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61  **).** - an arra
b750: 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a  y of two (void *
b760: 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69  ) values. The fi
b770: 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74  rst (void *) act
b780: 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20  ually points.** 
b790: 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
b7a0: 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76   type (int (*)(v
b7b0: 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65  oid *)). In orde
b7c0: 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20  r to invoke the 
b7d0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62  connections.** b
b7e0: 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69  usy-handler, thi
b7f0: 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  s function shoul
b800: 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  d be invoked wit
b810: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f  h the second (vo
b820: 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20  id *) in.** the 
b830: 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c  array as the onl
b840: 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69  y argument. If i
b850: 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  t returns non-ze
b860: 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65  ro, then the ope
b870: 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  ration.** should
b880: 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20   be retried. If 
b890: 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  it returns zero,
b8a0: 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20   the custom VFS 
b8b0: 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74  should abandon t
b8c0: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70  he.** current op
b8d0: 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c  eration..**.** <
b8e0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b8f0: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d  L_TEMPFILENAME]]
b900: 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e  .** ^Application
b910: 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20   can invoke the 
b920: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
b930: 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65  MPFILENAME] file
b940: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68  -control.** to h
b950: 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72  ave SQLite gener
b960: 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61  ate a.** tempora
b970: 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e  ry filename usin
b980: 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
b990: 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c  ithm that is fol
b9a0: 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74  lowed to generat
b9b0: 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
b9c0: 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d  ilenames for TEM
b9d0: 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68  P tables and oth
b9e0: 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73  er internal uses
b9f0: 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65  .  The.** argume
ba00: 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63  nt should be a c
ba10: 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c  har** which will
ba20: 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20   be filled with 
ba30: 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  the filename.** 
ba40: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
ba50: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
ba60: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
ba70: 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65  c()].  The calle
ba80: 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f  r should.** invo
ba90: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ke [sqlite3_free
baa0: 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c  ()] on the resul
bab0: 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d  t to avoid a mem
bac0: 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20  ory leak..**.** 
bad0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
bae0: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a  TL_MMAP_SIZE]].*
baf0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
bb00: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66  NTL_MMAP_SIZE] f
bb10: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
bb20: 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20  sed to query or 
bb30: 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d  set the.** maxim
bb40: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  um number of byt
bb50: 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20  es that will be 
bb60: 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d  used for memory-
bb70: 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54  mapped I/O..** T
bb80: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
bb90: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
bba0: 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69  lue of type sqli
bbb0: 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a  te3_int64 that.*
bbc0: 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79  * is an advisory
bbd0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
bbe0: 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
bbf0: 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d  file to memory m
bc00: 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e  ap.  The.** poin
bc10: 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74  ter is overwritt
bc20: 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20  en with the old 
bc30: 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69  value.  The limi
bc40: 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  t is not changed
bc50: 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65   if.** the value
bc60: 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e   originally poin
bc70: 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69  ted to is negati
bc80: 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63  ve, and so the c
bc90: 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a  urrent limit .**
bca0: 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20   can be queried 
bcb0: 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20  by passing in a 
bcc0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67  pointer to a neg
bcd0: 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54  ative number.  T
bce0: 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74  his.** file-cont
bcf0: 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65  rol is used inte
bd00: 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d  rnally to implem
bd10: 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  ent [PRAGMA mmap
bd20: 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  _size]..**.** <l
bd30: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bd40: 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20  _TRACE]].** The 
bd50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
bd60: 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ACE] file contro
bd70: 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73  l provides advis
bd80: 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ory information.
bd90: 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62  ** to the VFS ab
bda0: 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67  out what the hig
bdb0: 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68  her layers of th
bdc0: 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61  e SQLite stack a
bdd0: 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69  re doing..** Thi
bde0: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
bdf0: 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56  s used by some V
be00: 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63  FS activity trac
be10: 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20  ing [shims]..** 
be20: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
be30: 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
be40: 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65  d string.  Highe
be50: 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a  r layers in the.
be60: 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  ** SQLite stack 
be70: 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73  may generate ins
be80: 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66  tances of this f
be90: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a  ile control if.*
bea0: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  * the [SQLITE_US
beb0: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63  E_FCNTL_TRACE] c
bec0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
bed0: 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
bee0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
bef0: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
bf00: 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  D]].** The [SQLI
bf10: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
bf20: 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ED] file control
bf30: 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20   interprets its 
bf40: 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a  argument as a.**
bf50: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
bf60: 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72  nteger and it wr
bf70: 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69  ites a boolean i
bf80: 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72  nto that integer
bf90: 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e   depending.** on
bfa0: 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
bfb0: 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65  the file has bee
bfc0: 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64  n renamed, moved
bfd0: 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e  , or deleted sin
bfe0: 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72  ce it.** was fir
bff0: 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a  st opened..**.**
c000: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c010: 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41  NTL_WIN32_GET_HA
c020: 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NDLE]].** The [S
c030: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
c040: 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70  2_GET_HANDLE] op
c050: 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64  code can be used
c060: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a   to obtain the.*
c070: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74  * underlying nat
c080: 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  ive file handle 
c090: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
c0a0: 61 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20  a file handle.  
c0b0: 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e  This file.** con
c0c0: 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20  trol interprets 
c0d0: 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20  its argument as 
c0e0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
c0f0: 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c  ative file handl
c100: 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20  e and.** writes 
c110: 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 76 61  the resulting va
c120: 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  lue there..**.**
c130: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c140: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41  NTL_WIN32_SET_HA
c150: 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NDLE]].** The [S
c160: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
c170: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70  2_SET_HANDLE] op
c180: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
c190: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
c1a0: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
c1b0: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
c1c0: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77  rol method to sw
c1d0: 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64  ap the file hand
c1e0: 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a  le with the one.
c1f0: 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
c200: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
c210: 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69  nt.  This capabi
c220: 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72  lity is used dur
c230: 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61  ing testing.** a
c240: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  nd only needs to
c250: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68   be supported wh
c260: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69  en SQLITE_TEST i
c270: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  s defined..**.**
c280: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c290: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a  NTL_WAL_BLOCK]].
c2a0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
c2b0: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20  CNTL_WAL_BLOCK] 
c2c0: 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74  is a signal to t
c2d0: 68 65 20 56 46 53 20 6c 61 79 65 72 20 74 68 61  he VFS layer tha
c2e0: 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65  t it might.** be
c2f0: 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f   advantageous to
c300: 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65   block on the ne
c310: 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74  xt WAL lock if t
c320: 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69  he lock is not i
c330: 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76  mmediately.** av
c340: 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41  ailable.  The WA
c350: 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73 73 75  L subsystem issu
c360: 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64  es this signal d
c370: 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69  uring rare.** ci
c380: 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f  rcumstances in o
c390: 72 64 65 72 20 74 6f 20 66 69 78 20 61 20 70 72  rder to fix a pr
c3a0: 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72  oblem with prior
c3b0: 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ity inversion..*
c3c0: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
c3d0: 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65  hould <em>not</e
c3e0: 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c 65  m> use this file
c3f0: 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  -control..**.** 
c400: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
c410: 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54  TL_ZIPVFS]].** T
c420: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
c430: 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20  _ZIPVFS] opcode 
c440: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  is implemented b
c450: 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41  y zipvfs only. A
c460: 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20  ll other.** VFS 
c470: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51  should return SQ
c480: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f  LITE_NOTFOUND fo
c490: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a  r this opcode..*
c4a0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
c4b0: 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a  E_FCNTL_RBU]].**
c4c0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
c4d0: 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69  TL_RBU] opcode i
c4e0: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79  s implemented by
c4f0: 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53   the special VFS
c500: 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20   used by.** the 
c510: 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e  RBU extension on
c520: 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56  ly.  All other V
c530: 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  FS should return
c540: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
c550: 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63   for.** this opc
c560: 6f 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ode.  .**.** <li
c570: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
c580: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49  BEGIN_ATOMIC_WRI
c590: 54 45 5d 5d 0a 2a 2a 20 49 66 20 74 68 65 20 5b  TE]].** If the [
c5a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
c5b0: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
c5c0: 20 6f 70 63 6f 64 65 20 72 65 74 75 72 6e 73 20   opcode returns 
c5d0: 53 51 4c 49 54 45 5f 4f 4b 2c 20 74 68 65 6e 0a  SQLITE_OK, then.
c5e0: 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73 63  ** the file desc
c5f0: 72 69 70 74 6f 72 20 69 73 20 70 6c 61 63 65 64  riptor is placed
c600: 20 69 6e 20 22 62 61 74 63 68 20 77 72 69 74 65   in "batch write
c610: 20 6d 6f 64 65 22 2c 20 77 68 69 63 68 0a 2a 2a   mode", which.**
c620: 20 6d 65 61 6e 73 20 61 6c 6c 20 73 75 62 73 65   means all subse
c630: 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65 72  quent write oper
c640: 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 20 64  ations will be d
c650: 65 66 65 72 72 65 64 20 61 6e 64 20 64 6f 6e 65  eferred and done
c660: 0a 2a 2a 20 61 74 6f 6d 69 63 61 6c 6c 79 20 61  .** atomically a
c670: 74 20 74 68 65 20 6e 65 78 74 20 5b 53 51 4c 49  t the next [SQLI
c680: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
c690: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 20 20  ATOMIC_WRITE].  
c6a0: 53 79 73 74 65 6d 73 0a 2a 2a 20 74 68 61 74 20  Systems.** that 
c6b0: 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 62  do not support b
c6c0: 61 74 63 68 20 61 74 6f 6d 69 63 20 77 72 69 74  atch atomic writ
c6d0: 65 73 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  es will return S
c6e0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 2e 0a  QLITE_NOTFOUND..
c6f0: 2a 2a 20 5e 46 6f 6c 6c 6f 77 69 6e 67 20 61 20  ** ^Following a 
c700: 73 75 63 63 65 73 73 66 75 6c 20 53 51 4c 49 54  successful SQLIT
c710: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54  E_FCNTL_BEGIN_AT
c720: 4f 4d 49 43 5f 57 52 49 54 45 20 61 6e 64 20 70  OMIC_WRITE and p
c730: 72 69 6f 72 20 74 6f 0a 2a 2a 20 74 68 65 20 63  rior to.** the c
c740: 6c 6f 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46  losing [SQLITE_F
c750: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d  CNTL_COMMIT_ATOM
c760: 49 43 5f 57 52 49 54 45 5d 20 6f 72 0a 2a 2a 20  IC_WRITE] or.** 
c770: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f  [SQLITE_FCNTL_RO
c780: 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52  LLBACK_ATOMIC_WR
c790: 49 54 45 5d 2c 20 53 51 4c 69 74 65 20 77 69 6c  ITE], SQLite wil
c7a0: 6c 20 6d 61 6b 65 0a 2a 2a 20 6e 6f 20 56 46 53  l make.** no VFS
c7b0: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 73   interface calls
c7c0: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 73 71   on the same [sq
c7d0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 66 69 6c 65  lite3_file] file
c7e0: 20 64 65 73 63 72 69 70 74 6f 72 0a 2a 2a 20 65   descriptor.** e
c7f0: 78 63 65 70 74 20 66 6f 72 20 63 61 6c 6c 73 20  xcept for calls 
c800: 74 6f 20 74 68 65 20 78 57 72 69 74 65 20 6d 65  to the xWrite me
c810: 74 68 6f 64 20 61 6e 64 20 74 68 65 20 78 46 69  thod and the xFi
c820: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
c830: 0a 2a 2a 20 77 69 74 68 20 5b 53 51 4c 49 54 45  .** with [SQLITE
c840: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
c850: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
c860: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
c870: 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IT_ATOMIC_WRITE]
c880: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
c890: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54  _FCNTL_COMMIT_AT
c8a0: 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f  OMIC_WRITE] opco
c8b0: 64 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72  de causes all wr
c8c0: 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e  ite.** operation
c8d0: 73 20 73 69 6e 63 65 20 74 68 65 20 70 72 65 76  s since the prev
c8e0: 69 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c 20  ious successful 
c8f0: 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c  call to .** [SQL
c900: 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f  ITE_FCNTL_BEGIN_
c910: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f  ATOMIC_WRITE] to
c920: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 61 74   be performed at
c930: 6f 6d 69 63 61 6c 6c 79 2e 0a 2a 2a 20 54 68 69  omically..** Thi
c940: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  s file control r
c950: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
c960: 4b 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  K] if and only i
c970: 66 20 74 68 65 20 77 72 69 74 65 73 20 77 65 72  f the writes wer
c980: 65 0a 2a 2a 20 61 6c 6c 20 70 65 72 66 6f 72 6d  e.** all perform
c990: 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  ed successfully 
c9a0: 61 6e 64 20 68 61 76 65 20 62 65 65 6e 20 63 6f  and have been co
c9b0: 6d 6d 69 74 74 65 64 20 74 6f 20 70 65 72 73 69  mmitted to persi
c9c0: 73 74 65 6e 74 20 73 74 6f 72 61 67 65 2e 0a 2a  stent storage..*
c9d0: 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66  * ^Regardless of
c9e0: 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
c9f0: 69 74 20 69 73 20 73 75 63 63 65 73 73 66 75 6c  it is successful
ca00: 2c 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74  , this file cont
ca10: 72 6f 6c 20 74 61 6b 65 73 0a 2a 2a 20 74 68 65  rol takes.** the
ca20: 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72   file descriptor
ca30: 20 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77 72   out of batch wr
ca40: 69 74 65 20 6d 6f 64 65 20 73 6f 20 74 68 61 74  ite mode so that
ca50: 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a   all subsequent.
ca60: 2a 2a 20 77 72 69 74 65 20 6f 70 65 72 61 74 69  ** write operati
ca70: 6f 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e 64  ons are independ
ca80: 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ent..** ^SQLite 
ca90: 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
caa0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
cab0: 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49  OMMIT_ATOMIC_WRI
cac0: 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20  TE without.** a 
cad0: 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
cae0: 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45   call to [SQLITE
caf0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
cb00: 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a  MIC_WRITE]..**.*
cb10: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
cb20: 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54  CNTL_ROLLBACK_AT
cb30: 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20  OMIC_WRITE]].** 
cb40: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
cb50: 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49  L_ROLLBACK_ATOMI
cb60: 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  C_WRITE] opcode 
cb70: 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74 65  causes all write
cb80: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20 73  .** operations s
cb90: 69 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f 75  ince the previou
cba0: 73 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  s successful cal
cbb0: 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  l to .** [SQLITE
cbc0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
cbd0: 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62 65  MIC_WRITE] to be
cbe0: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
cbf0: 20 5e 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74   ^This file cont
cc00: 72 6f 6c 20 74 61 6b 65 73 20 74 68 65 20 66 69  rol takes the fi
cc10: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20 6f 75  le descriptor ou
cc20: 74 20 6f 66 20 62 61 74 63 68 20 77 72 69 74 65  t of batch write
cc30: 20 6d 6f 64 65 0a 2a 2a 20 73 6f 20 74 68 61 74   mode.** so that
cc40: 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
cc50: 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  write operations
cc60: 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65 6e 74   are independent
cc70: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
cc80: 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 53  l never invoke S
cc90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c  QLITE_FCNTL_ROLL
cca0: 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54  BACK_ATOMIC_WRIT
ccb0: 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70  E without.** a p
ccc0: 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
ccd0: 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f  call to [SQLITE_
cce0: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
ccf0: 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a  IC_WRITE]..**.**
cd00: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
cd10: 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54  NTL_LOCK_TIMEOUT
cd20: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
cd30: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d  E_FCNTL_LOCK_TIM
cd40: 45 4f 55 54 5d 20 6f 70 63 6f 64 65 20 63 61 75  EOUT] opcode cau
cd50: 73 65 73 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ses attempts to 
cd60: 6f 62 74 61 69 6e 0a 2a 2a 20 61 20 66 69 6c 65  obtain.** a file
cd70: 20 6c 6f 63 6b 20 75 73 69 6e 67 20 74 68 65 20   lock using the 
cd80: 78 4c 6f 63 6b 20 6f 72 20 78 53 68 6d 4c 6f 63  xLock or xShmLoc
cd90: 6b 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65  k methods of the
cda0: 20 56 46 53 20 74 6f 20 77 61 69 74 0a 2a 2a 20   VFS to wait.** 
cdb0: 66 6f 72 20 75 70 20 74 6f 20 4d 20 6d 69 6c 6c  for up to M mill
cdc0: 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20  iseconds before 
cdd0: 66 61 69 6c 69 6e 67 2c 20 77 68 65 72 65 20 4d  failing, where M
cde0: 20 69 73 20 74 68 65 20 73 69 6e 67 6c 65 20 0a   is the single .
cdf0: 2a 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  ** unsigned inte
ce00: 67 65 72 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ger parameter..*
ce10: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </ul>.*/.#defi
ce20: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
ce30: 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20  LOCKSTATE       
ce40: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
ce50: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47  e SQLITE_FCNTL_G
ce60: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
ce70: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
ce80: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45   SQLITE_FCNTL_SE
ce90: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
cea0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
ceb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53  SQLITE_FCNTL_LAS
cec0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
ced0: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
cee0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
cef0: 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  _HINT           
cf00: 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
cf10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
cf20: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  _SIZE           
cf30: 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
cf40: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
cf50: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20  OINTER          
cf60: 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
cf70: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
cf80: 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20  ITTED           
cf90: 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
cfa0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
cfb0: 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20  _RETRY          
cfc0: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
cfd0: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
cfe0: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30  AL            10
cff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d000: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20  FCNTL_OVERWRITE 
d010: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a               11.
d020: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d030: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20  CNTL_VFSNAME    
d040: 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23              12.#
d050: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d060: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
d070: 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64  ERWRITE    13.#d
d080: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d090: 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TL_PRAGMA       
d0a0: 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65            14.#de
d0b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d0c0: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20  L_BUSYHANDLER   
d0d0: 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66           15.#def
d0e0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d0f0: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20  _TEMPFILENAME   
d100: 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69          16.#defi
d110: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d120: 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20  MMAP_SIZE       
d130: 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e         18.#defin
d140: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
d150: 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20  RACE            
d160: 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65        19.#define
d170: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41   SQLITE_FCNTL_HA
d180: 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20  S_MOVED         
d190: 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20       20.#define 
d1a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
d1b0: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
d1c0: 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53      21.#define S
d1d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
d1e0: 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20  IT_PHASETWO     
d1f0: 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51     22.#define SQ
d200: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
d210: 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20  _SET_HANDLE     
d220: 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c    23.#define SQL
d230: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
d240: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  OCK             
d250: 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   24.#define SQLI
d260: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20  TE_FCNTL_ZIPVFS 
d270: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d280: 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  25.#define SQLIT
d290: 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20  E_FCNTL_RBU     
d2a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
d2b0: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
d2c0: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
d2d0: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 32 37  ER            27
d2e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d2f0: 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f  FCNTL_JOURNAL_PO
d300: 49 4e 54 45 52 20 20 20 20 20 20 20 20 32 38 0a  INTER        28.
d310: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d320: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
d330: 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a 23  ANDLE       29.#
d340: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d350: 4e 54 4c 5f 50 44 42 20 20 20 20 20 20 20 20 20  NTL_PDB         
d360: 20 20 20 20 20 20 20 20 20 20 20 33 30 0a 23 64             30.#d
d370: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d380: 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f  TL_BEGIN_ATOMIC_
d390: 57 52 49 54 45 20 20 20 20 20 33 31 0a 23 64 65  WRITE     31.#de
d3a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d3b0: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
d3c0: 57 52 49 54 45 20 20 20 20 33 32 0a 23 64 65 66  WRITE    32.#def
d3d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d3e0: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
d3f0: 5f 57 52 49 54 45 20 20 33 33 0a 23 64 65 66 69  _WRITE  33.#defi
d400: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d410: 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54 20 20 20 20  LOCK_TIMEOUT    
d420: 20 20 20 20 20 20 20 33 34 0a 23 64 65 66 69 6e         34.#defin
d430: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  e SQLITE_FCNTL_F
d440: 49 4c 45 49 44 20 20 20 20 20 20 20 20 20 20 20  ILEID           
d450: 20 20 20 20 20 20 33 35 0a 23 64 65 66 69 6e 65        35.#define
d460: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45   SQLITE_FCNTL_SE
d470: 52 56 45 52 5f 4d 4f 44 45 20 20 20 20 20 20 20  RVER_MODE       
d480: 20 20 20 20 20 33 36 0a 23 64 65 66 69 6e 65 20       36.#define 
d490: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 52  SQLITE_FCNTL_SER
d4a0: 56 45 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20  VER_SHMOPEN     
d4b0: 20 20 20 20 33 37 0a 23 64 65 66 69 6e 65 20 53      37.#define S
d4c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 52 56  QLITE_FCNTL_SERV
d4d0: 45 52 5f 53 48 4d 4f 50 45 4e 32 20 20 20 20 20  ER_SHMOPEN2     
d4e0: 20 20 20 33 38 0a 23 64 65 66 69 6e 65 20 53 51     38.#define SQ
d4f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 52 56 45  LITE_FCNTL_SERVE
d500: 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20  R_SHMLOCK       
d510: 20 20 33 39 0a 23 64 65 66 69 6e 65 20 53 51 4c    39.#define SQL
d520: 49 54 45 5f 46 43 4e 54 4c 5f 53 45 52 56 45 52  ITE_FCNTL_SERVER
d530: 5f 53 48 4d 43 4c 4f 53 45 20 20 20 20 20 20 20  _SHMCLOSE       
d540: 20 34 30 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74   40../* deprecat
d550: 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66  ed names */.#def
d560: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c  ine SQLITE_GET_L
d570: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
d580: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47    SQLITE_FCNTL_G
d590: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
d5a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d5b0: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
d5c0: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43  E      SQLITE_FC
d5d0: 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_SET_LOCKPROX
d5e0: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51  YFILE.#define SQ
d5f0: 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  LITE_LAST_ERRNO 
d600: 20 20 20 20 20 20 20 20 20 20 20 20 53 51 4c 49              SQLI
d610: 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52  TE_FCNTL_LAST_ER
d620: 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  RNO.../*.** CAPI
d630: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
d640: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  le.**.** The mut
d650: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
d660: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
d670: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
d680: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
d690: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
d6a0: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
d6b0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
d6c0: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
d6d0: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
d6e0: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
d6f0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
d700: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
d710: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
d720: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
d730: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
d740: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
d750: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
d760: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
d770: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
d780: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
d790: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
d7a0: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
d7b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64  * CAPI3REF: Load
d7c0: 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 54  able Extension T
d7d0: 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69  hunk.**.** A poi
d7e0: 6e 74 65 72 20 74 6f 20 74 68 65 20 6f 70 61 71  nter to the opaq
d7f0: 75 65 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  ue sqlite3_api_r
d800: 6f 75 74 69 6e 65 73 20 73 74 72 75 63 74 75 72  outines structur
d810: 65 20 69 73 20 70 61 73 73 65 64 20 61 73 0a 2a  e is passed as.*
d820: 2a 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  * the third para
d830: 6d 65 74 65 72 20 74 6f 20 65 6e 74 72 79 20 70  meter to entry p
d840: 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f 61 64 61 62  oints of [loadab
d850: 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 5d 2e 20  le extensions]. 
d860: 20 54 68 69 73 0a 2a 2a 20 73 74 72 75 63 74 75   This.** structu
d870: 72 65 20 6d 75 73 74 20 62 65 20 74 79 70 65 64  re must be typed
d880: 65 66 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  efed in order to
d890: 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 63 6f 6d   work around com
d8a0: 70 69 6c 65 72 20 77 61 72 6e 69 6e 67 73 0a 2a  piler warnings.*
d8b0: 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c 61 74 66 6f  * on some platfo
d8c0: 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  rms..*/.typedef 
d8d0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 61  struct sqlite3_a
d8e0: 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 71 6c 69  pi_routines sqli
d8f0: 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73  te3_api_routines
d900: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
d910: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
d920: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
d930: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
d940: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
d950: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
d960: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
d970: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
d980: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
d990: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
d9a0: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
d9b0: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
d9c0: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
d9d0: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
d9e0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
d9f0: 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b  ".  See.** the [
da00: 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65  VFS | VFS docume
da10: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72  ntation] for fur
da20: 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ther information
da30: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 56 46 53 20  ..**.** The VFS 
da40: 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 6f 6d  interface is som
da50: 65 74 69 6d 65 73 20 65 78 74 65 6e 64 65 64 20  etimes extended 
da60: 62 79 20 61 64 64 69 6e 67 20 6e 65 77 20 6d 65  by adding new me
da70: 74 68 6f 64 73 20 6f 6e 74 6f 0a 2a 2a 20 74 68  thods onto.** th
da80: 65 20 65 6e 64 2e 20 20 45 61 63 68 20 74 69 6d  e end.  Each tim
da90: 65 20 73 75 63 68 20 61 6e 20 65 78 74 65 6e 73  e such an extens
daa0: 69 6f 6e 20 6f 63 63 75 72 73 2c 20 74 68 65 20  ion occurs, the 
dab0: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 0a 2a  iVersion field.*
dac0: 2a 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64  * is incremented
dad0: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 20  .  The iVersion 
dae0: 76 61 6c 75 65 20 73 74 61 72 74 65 64 20 6f 75  value started ou
daf0: 74 20 61 73 20 31 20 69 6e 0a 2a 2a 20 53 51 4c  t as 1 in.** SQL
db00: 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 35  ite [version 3.5
db10: 2e 30 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33  .0] on [dateof:3
db20: 2e 35 2e 30 5d 2c 20 74 68 65 6e 20 69 6e 63 72  .5.0], then incr
db30: 65 61 73 65 64 20 74 6f 20 32 0a 2a 2a 20 77 69  eased to 2.** wi
db40: 74 68 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69  th SQLite [versi
db50: 6f 6e 20 33 2e 37 2e 30 5d 20 6f 6e 20 5b 64 61  on 3.7.0] on [da
db60: 74 65 6f 66 3a 33 2e 37 2e 30 5d 2c 20 61 6e 64  teof:3.7.0], and
db70: 20 74 68 65 6e 20 69 6e 63 72 65 61 73 65 64 0a   then increased.
db80: 2a 2a 20 74 6f 20 33 20 77 69 74 68 20 53 51 4c  ** to 3 with SQL
db90: 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37  ite [version 3.7
dba0: 2e 36 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33  .6] on [dateof:3
dbb0: 2e 37 2e 36 5d 2e 20 20 41 64 64 69 74 69 6f 6e  .7.6].  Addition
dbc0: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 6d 61 79  al fields.** may
dbd0: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
dbe0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
dbf0: 6f 62 6a 65 63 74 20 61 6e 64 20 74 68 65 20 69  object and the i
dc00: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 0a 2a 2a  Version value.**
dc10: 20 6d 61 79 20 69 6e 63 72 65 61 73 65 20 61 67   may increase ag
dc20: 61 69 6e 20 69 6e 20 66 75 74 75 72 65 20 76 65  ain in future ve
dc30: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
dc40: 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  ..** Note that t
dc50: 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  he structure.** 
dc60: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
dc70: 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65  fs object change
dc80: 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 69 74  s in the transit
dc90: 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 53 51 4c 69  ion from.** SQLi
dca0: 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 35 2e  te [version 3.5.
dcb0: 39 5d 20 74 6f 20 5b 76 65 72 73 69 6f 6e 20 33  9] to [version 3
dcc0: 2e 36 2e 30 5d 20 6f 6e 20 5b 64 61 74 65 6f 66  .6.0] on [dateof
dcd0: 3a 33 2e 36 2e 30 5d 0a 2a 2a 20 61 6e 64 20 79  :3.6.0].** and y
dce0: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
dcf0: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 20 6d 6f  field was not mo
dd00: 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  dified..**.** Th
dd10: 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64  e szOsFile field
dd20: 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
dd30: 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b  the subclassed [
dd40: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a  sqlite3_file].**
dd50: 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20   structure used 
dd60: 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78  by this VFS.  mx
dd70: 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20  Pathname is the 
dd80: 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
dd90: 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20  f.** a pathname 
dda0: 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a  in this VFS..**.
ddb0: 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71  ** Registered sq
ddc0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
ddd0: 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20  s are kept on a 
dde0: 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d  linked list form
ddf0: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65  ed by.** the pNe
de00: 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  xt pointer.  The
de10: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65   [sqlite3_vfs_re
de20: 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64  gister()].** and
de30: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e   [sqlite3_vfs_un
de40: 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65  register()] inte
de50: 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68  rfaces manage th
de60: 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20  is list.** in a 
de70: 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e  thread-safe way.
de80: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
de90: 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72  fs_find()] inter
dea0: 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73  face.** searches
deb0: 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74   the list.  Neit
dec0: 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  her the applicat
ded0: 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65  ion code nor the
dee0: 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   VFS.** implemen
def0: 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  tation should us
df00: 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  e the pNext poin
df10: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ter..**.** The p
df20: 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68  Next field is th
df30: 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20  e only field in 
df40: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
df50: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61  ** structure tha
df60: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76  t SQLite will ev
df70: 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69  er modify.  SQLi
df80: 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63  te will only acc
df90: 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79  ess.** or modify
dfa0: 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c   this field whil
dfb0: 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74  e holding a part
dfc0: 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75  icular static mu
dfd0: 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  tex..** The appl
dfe0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
dff0: 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74  ever modify anyt
e000: 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20  hing within the 
e010: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f  sqlite3_vfs.** o
e020: 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f  bject once the o
e030: 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72  bject has been r
e040: 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a  egistered..**.**
e050: 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64   The zName field
e060: 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20   holds the name 
e070: 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c  of the VFS modul
e080: 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73  e.  The name mus
e090: 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61  t.** be unique a
e0a0: 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f  cross all VFS mo
e0b0: 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73  dules..**.** [[s
e0c0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
e0d0: 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  ]].** ^SQLite gu
e0e0: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
e0f0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
e100: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
e110: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
e120: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
e130: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
e140: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
e150: 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70  ame() with an op
e160: 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64  tional suffix ad
e170: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75  ded..** ^If a su
e180: 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f  ffix is added to
e190: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
e1a0: 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c  arameter, it wil
e1b0: 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20  l.** consist of 
e1c0: 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61  a single "-" cha
e1d0: 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20  racter followed 
e1e0: 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a  by no more than.
e1f0: 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72  ** 11 alphanumer
e200: 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68  ic and/or "-" ch
e210: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51  aracters..** ^SQ
e220: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
e230: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
e240: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
e250: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
e260: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
e270: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
e280: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
e290: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
e2a0: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
e2b0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
e2c0: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
e2d0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
e2e0: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
e2f0: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
e300: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
e310: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
e320: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
e330: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
e340: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
e350: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
e360: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
e370: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
e380: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
e390: 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76  e file.  ^Whenev
e3a0: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
e3b0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
e3c0: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
e3d0: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
e3e0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
e3f0: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
e400: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
e410: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
e420: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  OSE]..**.** The 
e430: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
e440: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
e450: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
e460: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
e470: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
e480: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
e490: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
e4a0: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
e4b0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
e4c0: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
e4d0: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
e4e0: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
e4f0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
e500: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
e510: 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49  N_CREATE]. .** I
e520: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
e530: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
e540: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
e550: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
e560: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
e570: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20  PEN_READONLY].  
e580: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70  Other bits in *p
e590: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20  OutFlags may be 
e5a0: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c  set..**.** ^(SQL
e5b0: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
e5c0: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
e5d0: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
e5e0: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
e5f0: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
e600: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
e610: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a  ng opened:.**.**
e620: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
e630: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
e640: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
e650: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
e660: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
e670: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
e680: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
e690: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
e6a0: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
e6b0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
e6c0: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
e6d0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
e6e0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
e6f0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
e700: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
e710: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
e720: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41   [SQLITE_OPEN_WA
e730: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  L].** </ul>)^.**
e740: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
e750: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
e760: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
e770: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
e780: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
e790: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
e7a0: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
e7b0: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
e7c0: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
e7d0: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
e7e0: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
e7f0: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
e800: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
e810: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
e820: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
e830: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
e840: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
e850: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
e860: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
e870: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
e880: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
e890: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
e8a0: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
e8b0: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
e8c0: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
e8d0: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
e8e0: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
e8f0: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
e900: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
e910: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
e920: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
e930: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
e940: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
e950: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
e960: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
e970: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
e980: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
e990: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
e9a0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
e9b0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
e9c0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
e9d0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
e9e0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
e9f0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
ea00: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
ea10: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
ea20: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
ea30: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
ea40: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
ea50: 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53  closed.  ^The [S
ea60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
ea70: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c  EONCLOSE].** wil
ea80: 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d  l be set for TEM
ea90: 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20  P databases and 
eaa0: 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20  their journals, 
eab0: 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74  transient.** dat
eac0: 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a  abases, and subj
ead0: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ournals..**.** ^
eae0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
eaf0: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
eb00: 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
eb10: 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a  in conjunction.*
eb20: 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
eb30: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
eb40: 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20  flag, which are 
eb50: 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a  both directly.**
eb60: 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68   analogous to th
eb70: 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43  e O_EXCL and O_C
eb80: 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68  REAT flags of th
eb90: 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a  e POSIX open().*
eba0: 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49  * API.  The SQLI
ebb0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
ebc0: 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69  E flag, when pai
ebd0: 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  red with the .**
ebe0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
ebf0: 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20  ATE, is used to 
ec00: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69  indicate that fi
ec10: 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  le should always
ec20: 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20  .** be created, 
ec30: 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61  and that it is a
ec40: 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c  n error if it al
ec50: 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a  ready exists..**
ec60: 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69   It is <i>not</i
ec70: 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  > used to indica
ec80: 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  te the file shou
ec90: 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a  ld be opened .**
eca0: 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61   for exclusive a
ecb0: 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74  ccess..**.** ^At
ecc0: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
ecd0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
ece0: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
ecf0: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
ed00: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
ed10: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
ed20: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
ed30: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
ed40: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
ed50: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
ed60: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
ed70: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
ed80: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
ed90: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
eda0: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
edb0: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
edc0: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
edd0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
ede0: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
edf0: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
ee00: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
ee10: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
ee20: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
ee30: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
ee40: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
ee50: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
ee60: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
ee70: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
ee80: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
ee90: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
eea0: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
eeb0: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
eec0: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
eed0: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
eee0: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b  en call..**.** [
eef0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63  [sqlite3_vfs.xAc
ef00: 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66  cess]].** ^The f
ef10: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
ef20: 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62   xAccess() may b
ef30: 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  e [SQLITE_ACCESS
ef40: 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74  _EXISTS].** to t
ef50: 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73  est for the exis
ef60: 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c  tence of a file,
ef70: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
ef80: 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f  SS_READWRITE] to
ef90: 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72  .** test whether
efa0: 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61   a file is reada
efb0: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
efc0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
efd0: 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20  ESS_READ].** to 
efe0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
eff0: 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20  ile is at least 
f000: 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20  readable.   The 
f010: 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a  file can be a.**
f020: 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
f030: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  * ^SQLite will a
f040: 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61  lways allocate a
f050: 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61  t least mxPathna
f060: 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74  me+1 bytes for t
f070: 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66  he.** output buf
f080: 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  fer xFullPathnam
f090: 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69  e.  The exact si
f0a0: 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74  ze of the output
f0b0: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c   buffer.** is al
f0c0: 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70  so passed as a p
f0d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68  arameter to both
f0e0: 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68    methods. If th
f0f0: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
f100: 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20  ** is not large 
f110: 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f  enough, [SQLITE_
f120: 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64  CANTOPEN] should
f130: 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69   be returned. Si
f140: 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68  nce this is.** h
f150: 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61  andled as a fata
f160: 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74  l error by SQLit
f170: 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74  e, vfs implement
f180: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e  ations should en
f190: 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65  deavor.** to pre
f1a0: 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74  vent this by set
f1b0: 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20  ting mxPathname 
f1c0: 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c  to a sufficientl
f1d0: 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a  y large value..*
f1e0: 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  *.** The xRandom
f1f0: 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29  ness(), xSleep()
f200: 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  , xCurrentTime()
f210: 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69  , and xCurrentTi
f220: 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74  meInt64().** int
f230: 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20  erfaces are not 
f240: 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20  strictly a part 
f250: 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65  of the filesyste
f260: 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a  m, but they are.
f270: 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ** included in t
f280: 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65  he VFS structure
f290: 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73   for completenes
f2a0: 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  s..** The xRando
f2b0: 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e  mness() function
f2c0: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74   attempts to ret
f2d0: 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73  urn nBytes bytes
f2e0: 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c  .** of good-qual
f2f0: 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69  ity randomness i
f300: 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72  nto zOut.  The r
f310: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a  eturn value is.*
f320: 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d  * the actual num
f330: 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
f340: 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
f350: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65  ned..** The xSle
f360: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73  ep() method caus
f370: 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  es the calling t
f380: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66  hread to sleep f
f390: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74  or at.** least t
f3a0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63  he number of mic
f3b0: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e  roseconds given.
f3c0: 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54    ^The xCurrentT
f3d0: 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ime().** method 
f3e0: 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e  returns a Julian
f3f0: 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20   Day Number for 
f400: 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65  the current date
f410: 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20   and time as.** 
f420: 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
f430: 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20   value..** ^The 
f440: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
f450: 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  4() method retur
f460: 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65  ns, as an intege
f470: 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a  r, the Julian.**
f480: 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74   Day Number mult
f490: 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 30 30  iplied by 864000
f4a0: 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f  00 (the number o
f4b0: 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69  f milliseconds i
f4c0: 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20  n .** a 24-hour 
f4d0: 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69  day).  .** ^SQLi
f4e0: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
f4f0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
f500: 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65  4() method to ge
f510: 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  t the current.**
f520: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69   date and time i
f530: 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73  f that method is
f540: 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69   available (if i
f550: 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20  Version is 2 or 
f560: 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20  .** greater and 
f570: 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
f580: 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
f590: 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20  ) and will fall 
f5a0: 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72  back.** to xCurr
f5b0: 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 75  entTime() if xCu
f5c0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
f5d0: 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
f5e0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74  .**.** ^The xSet
f5f0: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47  SystemCall(), xG
f600: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
f610: 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43  and xNestSystemC
f620: 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73  all() interfaces
f630: 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64  .** are not used
f640: 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 63   by the SQLite c
f650: 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69  ore.  These opti
f660: 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  onal interfaces 
f670: 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  are provided.** 
f680: 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f  by some VFSes to
f690: 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 73 74   facilitate test
f6a0: 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20 63  ing of the VFS c
f6b0: 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69  ode. By overridi
f6c0: 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61  ng .** system ca
f6d0: 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f  lls with functio
f6e0: 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e  ns under its con
f6f0: 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f  trol, a test pro
f700: 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75  gram can.** simu
f710: 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20  late faults and 
f720: 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73  error conditions
f730: 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65   that would othe
f740: 72 77 69 73 65 20 62 65 20 64 69 66 66 69 63 75  rwise be difficu
f750: 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69  lt.** or impossi
f760: 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20  ble to induce.  
f770: 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 74 65  The set of syste
f780: 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e  m calls that can
f790: 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a   be overridden.*
f7a0: 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e  * varies from on
f7b0: 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72  e VFS to another
f7c0: 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76  , and from one v
f7d0: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61  ersion of the sa
f7e0: 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a  me VFS to the.**
f7f0: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
f800: 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74 68  ions that use th
f810: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
f820: 75 73 74 20 62 65 20 70 72 65 70 61 72 65 64 20  ust be prepared 
f830: 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c  for any.** or al
f840: 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72  l of these inter
f850: 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c  faces to be NULL
f860: 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62 65   or for their be
f870: 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65  havior to change
f880: 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c  .** from one rel
f890: 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74  ease to the next
f8a0: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
f8b0: 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74  must not attempt
f8c0: 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e   to access.** an
f8d0: 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f  y of these metho
f8e0: 64 73 20 69 66 20 74 68 65 20 69 56 65 72 73 69  ds if the iVersi
f8f0: 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69 73  on of the VFS is
f900: 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f   less than 3..*/
f910: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
f920: 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69  sqlite3_vfs sqli
f930: 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66  te3_vfs;.typedef
f940: 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
f950: 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69  syscall_ptr)(voi
f960: 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  d);.struct sqlit
f970: 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69  e3_vfs {.  int i
f980: 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20  Version;        
f990: 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65      /* Structure
f9a0: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
f9b0: 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f  (currently 3) */
f9c0: 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b  .  int szOsFile;
f9d0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
f9e0: 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65  ize of subclasse
f9f0: 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a  d sqlite3_file *
fa00: 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61  /.  int mxPathna
fa10: 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  me;          /* 
fa20: 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74  Maximum file pat
fa30: 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a  hname length */.
fa40: 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70    sqlite3_vfs *p
fa50: 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65  Next;      /* Ne
fa60: 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46  xt registered VF
fa70: 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  S */.  const cha
fa80: 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20  r *zName;       
fa90: 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20  /* Name of this 
faa0: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
fab0: 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tem */.  void *p
fac0: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
fad0: 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20    /* Pointer to 
fae0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63  application-spec
faf0: 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69  ific data */.  i
fb00: 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
fb10: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
fb20: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
fb30: 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20  ite3_file*,.    
fb40: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66             int f
fb50: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46  lags, int *pOutF
fb60: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
fb70: 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f  Delete)(sqlite3_
fb80: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
fb90: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e   *zName, int syn
fba0: 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  cDir);.  int (*x
fbb0: 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f  Access)(sqlite3_
fbc0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
fbd0: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61   *zName, int fla
fbe0: 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  gs, int *pResOut
fbf0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c  );.  int (*xFull
fc00: 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65  Pathname)(sqlite
fc10: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
fc20: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e  ar *zName, int n
fc30: 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  Out, char *zOut)
fc40: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f  ;.  void *(*xDlO
fc50: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
fc60: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
fc70: 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69  Filename);.  voi
fc80: 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71  d (*xDlError)(sq
fc90: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
fca0: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72  nByte, char *zEr
fcb0: 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a  rMsg);.  void (*
fcc0: 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65  (*xDlSym)(sqlite
fcd0: 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f  3_vfs*,void*, co
fce0: 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f  nst char *zSymbo
fcf0: 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69  l))(void);.  voi
fd00: 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71  d (*xDlClose)(sq
fd10: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64  lite3_vfs*, void
fd20: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e  *);.  int (*xRan
fd30: 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33  domness)(sqlite3
fd40: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
fd50: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
fd60: 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73   int (*xSleep)(s
fd70: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
fd80: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a   microseconds);.
fd90: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
fda0: 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  Time)(sqlite3_vf
fdb0: 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20  s*, double*);.  
fdc0: 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72  int (*xGetLastEr
fdd0: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
fde0: 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b  *, int, char *);
fdf0: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
fe00: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
fe10: 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66   in version 1 of
fe20: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
fe30: 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69  object.  ** defi
fe40: 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74  nition.  Those t
fe50: 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61  hat follow are a
fe60: 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20  dded in version 
fe70: 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a  2 or later.  */.
fe80: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
fe90: 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74  TimeInt64)(sqlit
fea0: 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33  e3_vfs*, sqlite3
feb0: 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20  _int64*);.  /*. 
fec0: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
fed0: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
fee0: 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66  sions 1 and 2 of
fef0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
ff00: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f  object..  ** Tho
ff10: 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72  se below are for
ff20: 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67   version 3 and g
ff30: 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69  reater..  */.  i
ff40: 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43  nt (*xSetSystemC
ff50: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
ff60: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
ff70: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79  Name, sqlite3_sy
ff80: 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71  scall_ptr);.  sq
ff90: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
ffa0: 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61  r (*xGetSystemCa
ffb0: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
ffc0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
ffd0: 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68  ame);.  const ch
ffe0: 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65  ar *(*xNextSyste
fff0: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
10000 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
10010 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20  *zName);.  /*.  
10020 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
10030 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
10040 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33  ions 1 through 3
10050 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
10060 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
10070 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62  New fields may b
10080 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 75  e appended in fu
10090 74 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20  ture versions.  
100a0 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a  The iVersion.  *
100b0 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63  * value will inc
100c0 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20  rement whenever 
100d0 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20  this happens. . 
100e0 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
100f0 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
10100 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46  r the xAccess VF
10110 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
10120 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
10130 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73  stants can be us
10140 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
10150 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
10160 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
10170 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  od of an [sqlite
10180 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20  3_vfs] object.  
10190 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a  They determine.*
101a0 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70  * what kind of p
101b0 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78  ermissions the x
101c0 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73  Access method is
101d0 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a   looking for..**
101e0 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
101f0 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20  ESS_EXISTS, the 
10200 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
10210 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20  * simply checks 
10220 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
10230 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68   exists..** With
10240 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
10250 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41  EADWRITE, the xA
10260 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
10270 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
10280 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f  he named directo
10290 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 64 61  ry is both reada
102a0 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
102b0 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f  .** (in other wo
102c0 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61  rds, if files ca
102d0 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f  n be added, remo
102e0 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64  ved, and renamed
102f0 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64   within.** the d
10300 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68  irectory)..** Th
10310 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
10320 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61  READWRITE consta
10330 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  nt is currently 
10340 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65  used only by the
10350 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  .** [temp_store_
10360 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
10370 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 63  ], though this c
10380 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61  ould change in a
10390 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61   future.** relea
103a0 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
103b0 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
103c0 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41  ESS_READ, the xA
103d0 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
103e0 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
103f0 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61  he file is reada
10400 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ble.  The SQLITE
10410 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e  _ACCESS_READ con
10420 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72  stant is.** curr
10430 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68  ently unused, th
10440 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 62 65  ough it might be
10450 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 75 72   used in a futur
10460 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20  e release of.** 
10470 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
10480 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
10490 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65  _EXISTS    0.#de
104a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
104b0 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 20 20  SS_READWRITE 1  
104c0 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41 47   /* Used by PRAG
104d0 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  MA temp_store_di
104e0 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69  rectory */.#defi
104f0 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
10500 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 20 2f  _READ      2   /
10510 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  * Unused */../*.
10520 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
10530 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c  gs for the xShmL
10540 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ock VFS method.*
10550 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
10560 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  er constants def
10570 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20  ine the various 
10580 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f  locking operatio
10590 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79  ns.** allowed by
105a0 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   the xShmLock me
105b0 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  thod of [sqlite3
105c0 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54  _io_methods].  T
105d0 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
105e0 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67  are the only leg
105f0 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  al combinations 
10600 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a  of flags to the.
10610 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  ** xShmLock meth
10620 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
10630 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
10640 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
10650 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c  _SHM_SHARED.** <
10660 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
10670 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
10680 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c  M_EXCLUSIVE.** <
10690 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
106a0 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  UNLOCK | SQLITE_
106b0 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c  SHM_SHARED.** <l
106c0 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  i>  SQLITE_SHM_U
106d0 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  NLOCK | SQLITE_S
106e0 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20  HM_EXCLUSIVE.** 
106f0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  </ul>.**.** When
10700 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20   unlocking, the 
10710 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45  same SHARED or E
10720 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75  XCLUSIVE flag mu
10730 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 61  st be supplied a
10740 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6f  s.** was given o
10750 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
10760 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a  ing lock.  .**.*
10770 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
10780 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69  ethod can transi
10790 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c  tion between unl
107a0 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44  ocked and SHARED
107b0 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75   or.** between u
107c0 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c  nlocked and EXCL
107d0 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f  USIVE.  It canno
107e0 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  t transition bet
107f0 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61  ween SHARED.** a
10800 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f  nd EXCLUSIVE..*/
10810 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10820 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  SHM_UNLOCK      
10830 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
10840 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20  E_SHM_LOCK      
10850 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
10860 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20  ITE_SHM_SHARED  
10870 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
10880 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
10890 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20  IVE    8../*.** 
108a0 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75  CAPI3REF: Maximu
108b0 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78  m xShmLock index
108c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
108d0 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73  ock method on [s
108e0 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
108f0 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65  s] may use value
10900 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61  s.** between 0 a
10910 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 62 6f  nd this upper bo
10920 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 73  und as its "offs
10930 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  et" argument..**
10940 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
10950 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65   will never atte
10960 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f  mpt to acquire o
10970 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c  r release a.** l
10980 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74  ock outside of t
10990 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65  his range.*/.#de
109a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
109b0 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a  NLOCK        8..
109c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
109d0 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20   Initialize The 
109e0 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
109f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
10a00 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
10a10 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a  outine initializ
10a20 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  es the.** SQLite
10a30 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20   library.  ^The 
10a40 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10a50 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65  () routine.** de
10a60 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65  allocates any re
10a70 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72  sources that wer
10a80 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
10a90 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10aa0 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e()..** These ro
10ab0 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67  utines are desig
10ac0 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72  ned to aid in pr
10ad0 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
10ae0 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74  tion and.** shut
10af0 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64  down on embedded
10b00 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73   systems.  Works
10b10 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69  tation applicati
10b20 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c  ons using.** SQL
10b30 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20  ite normally do 
10b40 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f  not need to invo
10b50 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65  ke either of the
10b60 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
10b70 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
10b80 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10b90 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
10ba0 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
10bb0 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74  s.** the first t
10bc0 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
10bd0 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
10be0 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c  ked during the l
10bf0 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68  ifetime of.** th
10c00 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  e process, or if
10c10 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
10c20 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
10c30 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
10c40 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  voked.** followi
10c50 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ng a call to sql
10c60 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
10c70 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65    ^(Only an effe
10c80 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66  ctive call.** of
10c90 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10ca0 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69  ize() does any i
10cb0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20  nitialization.  
10cc0 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a  All other calls.
10cd0 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  ** are harmless 
10ce0 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
10cf0 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
10d00 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20  3_shutdown() is 
10d10 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
10d20 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65  all if it is the
10d30 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74   first.** call t
10d40 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
10d50 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c  wn() since the l
10d60 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ast sqlite3_init
10d70 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c  ialize().  ^(Onl
10d80 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76  y.** an effectiv
10d90 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
10da0 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65  3_shutdown() doe
10db0 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69  s any deinitiali
10dc0 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f  zation..** All o
10dd0 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73  ther valid calls
10de0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
10df0 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c  down() are harml
10e00 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
10e10 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
10e20 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74  initialize() int
10e30 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64  erface is thread
10e40 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65  safe, but sqlite
10e50 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
10e60 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c  is not.  The sql
10e70 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
10e80 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f  interface must o
10e90 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72  nly be called fr
10ea0 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74  om a.** single t
10eb0 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e  hread.  All open
10ec0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10ed0 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20  ctions] must be 
10ee0 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a  closed and all.*
10ef0 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72  * other SQLite r
10f00 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65  esources must be
10f10 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69   deallocated pri
10f20 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a  or to invoking.*
10f30 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  * sqlite3_shutdo
10f40 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e  wn()..**.** Amon
10f50 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20  g other things, 
10f60 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  ^sqlite3_initial
10f70 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b  ize() will invok
10f80 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  e.** sqlite3_os_
10f90 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72  init().  Similar
10fa0 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75  ly, ^sqlite3_shu
10fb0 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20  tdown().** will 
10fc0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f  invoke sqlite3_o
10fd0 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  s_end()..**.** ^
10fe0 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
10ff0 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
11000 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
11010 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e  _OK] on success.
11020 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65  .** ^If for some
11030 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33   reason, sqlite3
11040 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
11050 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69   unable to initi
11060 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62  alize.** the lib
11070 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74  rary (perhaps it
11080 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
11090 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20  locate a needed 
110a0 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a  resource such.**
110b0 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20   as a mutex) it 
110c0 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f  returns an [erro
110d0 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68  r code] other th
110e0 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  an [SQLITE_OK]..
110f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
11100 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
11110 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
11120 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
11130 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51  many other.** SQ
11140 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
11150 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69  so that an appli
11160 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64  cation usually d
11170 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a  oes not need to.
11180 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
11190 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
111a0 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78  irectly.  For ex
111b0 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f  ample, [sqlite3_
111c0 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73  open()].** calls
111d0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
111e0 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c  ize() so the SQL
111f0 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
11200 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
11210 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64  y.** initialized
11220 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f   when [sqlite3_o
11230 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  pen()] is called
11240 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62   if it has not b
11250 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a  e initialized.**
11260 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65   already.  ^Howe
11270 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
11280 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
11290 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  the [SQLITE_OMIT
112a0 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f  _AUTOINIT].** co
112b0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
112c0 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f  n, then the auto
112d0 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73  matic calls to s
112e0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
112f0 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74  e().** are omitt
11300 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ed and the appli
11310 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c  cation must call
11320 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11330 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a  ize() directly.*
11340 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  * prior to using
11350 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
11360 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f  e interface.  Fo
11370 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62  r maximum portab
11380 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20  ility,.** it is 
11390 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
113a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c   applications al
113b0 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69  ways invoke sqli
113c0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
113d0 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69  .** directly pri
113e0 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
113f0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
11400 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20  erface.  Future 
11410 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53  releases.** of S
11420 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72  QLite may requir
11430 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65  e this.  In othe
11440 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68  r words, the beh
11450 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a  avior exhibited.
11460 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
11470 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
11480 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
11490 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63  OINIT] might bec
114a0 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75  ome the.** defau
114b0 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73  lt behavior in s
114c0 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
114d0 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
114e0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
114f0 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e  os_init() routin
11500 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67  e does operating
11510 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
11520 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  .** initializati
11530 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
11540 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73   library.  The s
11550 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
11560 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
11570 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
11580 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
11590 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b  ).  Typical task
115a0 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62  s.** performed b
115b0 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  y these routines
115c0 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74   include allocat
115d0 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ion or deallocat
115e0 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63  ion.** of static
115f0 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74   resources, init
11600 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c  ialization of gl
11610 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a  obal variables,.
11620 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20  ** setting up a 
11630 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
11640 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72  _vfs] module, or
11650 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61   setting up.** a
11660 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
11670 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71  ration using [sq
11680 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
11690 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
116a0 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
116b0 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65  ver invoke eithe
116c0 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
116d0 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
116e0 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63  3_os_end() direc
116f0 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63  tly.  The applic
11700 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c  ation should onl
11710 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  y invoke.** sqli
11720 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11730 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75   and sqlite3_shu
11740 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71  tdown().  The sq
11750 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
11760 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
11770 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  called automatic
11780 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
11790 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
117a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  .** sqlite3_os_e
117b0 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62  nd() is called b
117c0 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  y sqlite3_shutdo
117d0 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61  wn().  Appropria
117e0 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  te.** implementa
117f0 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65  tions for sqlite
11800 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
11810 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
11820 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e  .** are built in
11830 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69  to SQLite when i
11840 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  t is compiled fo
11850 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c  r Unix, Windows,
11860 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65   or OS/2..** Whe
11870 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73  n [custom builds
11880 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68   | built for oth
11890 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a  er platforms].**
118a0 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c   (using the [SQL
118b0 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20  ITE_OS_OTHER=1] 
118c0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
118d0 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c  option) the appl
118e0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70  ication must sup
118f0 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69  ply a suitable i
11900 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
11910 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  r.** sqlite3_os_
11920 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
11930 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e  e3_os_end().  An
11940 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
11950 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65  plied.** impleme
11960 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
11970 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20  e3_os_init() or 
11980 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
11990 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20  .** must return 
119a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
119b0 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20  uccess and some 
119c0 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64  other [error cod
119d0 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75  e] upon.** failu
119e0 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  re..*/.int sqlit
119f0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
11a00 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
11a10 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
11a20 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
11a30 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20  init(void);.int 
11a40 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76  sqlite3_os_end(v
11a50 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
11a60 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69  I3REF: Configuri
11a70 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ng The SQLite Li
11a80 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20  brary.**.** The 
11a90 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11aa0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
11ab0 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61  ed to make globa
11ac0 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  l configuration.
11ad0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51  ** changes to SQ
11ae0 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
11af0 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20   tune SQLite to 
11b00 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
11b10 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  ds of.** the app
11b20 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  lication.  The d
11b30 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
11b40 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e  tion is recommen
11b50 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20  ded for most.** 
11b60 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64  applications and
11b70 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   so this routine
11b80 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20   is usually not 
11b90 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69  necessary.  It i
11ba0 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f  s.** provided to
11bb0 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70   support rare ap
11bc0 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20  plications with 
11bd0 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a  unusual needs..*
11be0 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69  *.** <b>The sqli
11bf0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
11c00 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
11c10 72 65 61 64 73 61 66 65 2e 20 54 68 65 20 61 70  readsafe. The ap
11c20 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
11c30 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t ensure that no
11c40 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
11c50 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
11c60 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
11c70 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
11c80 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
11c90 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a  is running.</b>.
11ca0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
11cb0 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
11cc0 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  face.** may only
11cd0 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   be invoked prio
11ce0 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69  r to library ini
11cf0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e  tialization usin
11d00 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  g.** [sqlite3_in
11d10 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  itialize()] or a
11d20 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79  fter shutdown by
11d30 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
11d40 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  wn()]..** ^If sq
11d50 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
11d60 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  s called after [
11d70 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11d80 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65  ze()] and before
11d90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
11da0 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74  tdown()] then it
11db0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c   will return SQL
11dc0 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e  ITE_MISUSE..** N
11dd0 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
11de0 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66  at ^sqlite3_conf
11df0 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
11e00 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
11e10 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
11e20 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
11e30 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
11e40 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
11e50 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
11e60 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
11e70 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
11e80 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
11e90 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
11ea0 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
11eb0 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
11ec0 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
11ed0 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
11ee0 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
11ef0 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
11f00 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
11f10 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72  on the [configur
11f20 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
11f30 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
11f40 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
11f50 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
11f60 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
11f70 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
11f80 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
11f90 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
11fa0 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
11fb0 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
11fc0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
11fd0 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
11fe0 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
11ff0 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
12000 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
12010 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
12020 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
12030 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
12040 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
12050 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12060 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ns.** METHOD: sq
12070 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
12080 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
12090 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
120a0 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f   used to make co
120b0 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
120c0 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74  hanges to a [dat
120d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
120e0 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63  ].  The interfac
120f0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a  e is similar to.
12100 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
12110 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61  ig()] except tha
12120 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70  t the changes ap
12130 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a  ply to a single.
12140 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
12150 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66  nection] (specif
12160 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
12170 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a   argument)..**.*
12180 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
12190 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
121a0 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e  _db_config(D,V,.
121b0 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b  ..)  is the.** [
121c0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
121d0 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66  LOOKASIDE | conf
121e0 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20  iguration verb] 
121f0 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  - an integer cod
12200 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63  e .** that indic
12210 61 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74  ates what aspect
12220 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
12230 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
12240 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65   being configure
12250 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74  d..** Subsequent
12260 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20   arguments vary 
12270 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
12280 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76   configuration v
12290 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  erb..**.** ^Call
122a0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f  s to sqlite3_db_
122b0 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20  config() return 
122c0 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64  SQLITE_OK if and
122d0 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20   only if.** the 
122e0 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72  call is consider
122f0 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a  ed successful..*
12300 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62  /.int sqlite3_db
12310 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a  _config(sqlite3*
12320 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a  , int op, ...);.
12330 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12340 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
12350 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a  on Routines.**.*
12360 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
12370 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   this object def
12380 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
12390 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74  ce between SQLit
123a0 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76  e.** and low-lev
123b0 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
123c0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  tion routines..*
123d0 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  *.** This object
123e0 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79   is used in only
123f0 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68   one place in th
12400 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  e SQLite interfa
12410 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  ce..** A pointer
12420 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
12430 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  of this object i
12440 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
12450 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
12460 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65  nfig()] when the
12470 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12480 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c  ption is.** [SQL
12490 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
124a0 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  C] or [SQLITE_CO
124b0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e  NFIG_GETMALLOC].
124c0 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e    .** By creatin
124d0 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  g an instance of
124e0 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20   this object.** 
124f0 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74  and passing it t
12500 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
12510 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
12520 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75  G_MALLOC]).** du
12530 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ring configurati
12540 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  on, an applicati
12550 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61  on can specify a
12560 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
12570 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12580 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72  on subsystem for
12590 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66   SQLite to use f
125a0 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a  or all of its.**
125b0 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
125c0 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  needs..**.** Not
125d0 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f  e that SQLite co
125e0 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c  mes with several
125f0 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72   [built-in memor
12600 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a  y allocators].**
12610 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63   that are perfec
12620 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72  tly adequate for
12630 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e   the overwhelmin
12640 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70  g majority of ap
12650 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e  plications.** an
12660 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65  d that this obje
12670 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75  ct is only usefu
12680 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f  l to a tiny mino
12690 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
126a0 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65  ions.** with spe
126b0 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20  cialized memory 
126c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69  allocation requi
126d0 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f  rements.  This o
126e0 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f  bject is.** also
126f0 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
12700 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69  ting of SQLite i
12710 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69  n order to speci
12720 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
12730 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
12740 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c  cator that simul
12750 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d  ates memory out-
12760 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74  of-memory condit
12770 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72  ions in.** order
12780 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
12790 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20  SQLite recovers 
127a0 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20  gracefully from 
127b0 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f  such.** conditio
127c0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  ns..**.** The xM
127d0 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c  alloc, xRealloc,
127e0 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f   and xFree metho
127f0 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  ds must work lik
12800 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28  e the.** malloc(
12810 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ), realloc() and
12820 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e   free() function
12830 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
12840 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
12850 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
12860 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65  tees that the se
12870 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
12880 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20  .** xRealloc is 
12890 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72  always a value r
128a0 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69  eturned by a pri
128b0 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e  or call to xRoun
128c0 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  dup..**.** xSize
128d0 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
128e0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
128f0 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
12900 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
12910 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
12920 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
12930 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
12940 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
12950 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
12960 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
12970 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
12980 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
12990 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
129a0 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
129b0 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
129c0 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
129d0 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
129e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
129f0 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
12a00 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
12a10 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
12a20 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
12a30 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
12a40 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
12a50 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
12a60 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
12a70 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
12a80 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
12a90 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
12aa0 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
12ab0 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65  f 2..** Every me
12ac0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12ad0 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69  request coming i
12ae0 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74  n through [sqlit
12af0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  e3_malloc()].** 
12b00 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
12b10 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c  loc()] first cal
12b20 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66  ls xRoundup.  If
12b30 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e   xRoundup return
12b40 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61  s 0, .** that ca
12b50 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70  uses the corresp
12b60 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c  onding memory al
12b70 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c  location to fail
12b80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
12b90 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
12ba0 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
12bb0 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20  allocator.  For 
12bc0 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
12bd0 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
12be0 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
12bf0 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
12c00 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
12c10 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
12c20 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
12c30 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
12c40 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
12c50 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
12c60 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
12c70 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
12c80 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
12c90 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
12ca0 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
12cb0 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
12cc0 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
12cd0 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
12ce0 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
12cf0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64  *.** SQLite hold
12d00 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
12d10 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
12d20 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74  R] mutex when it
12d30 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20   invokes.** the 
12d40 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f  xInit method, so
12d50 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
12d60 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68  d need not be th
12d70 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a  readsafe.  The.*
12d80 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  * xShutdown meth
12d90 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65  od is only calle
12da0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
12db0 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69  shutdown()] so i
12dc0 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65  t does.** not ne
12dd0 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73  ed to be threads
12de0 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72  afe either.  For
12df0 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f   all other metho
12e00 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f  ds, SQLite.** ho
12e10 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
12e20 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
12e30 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20  ] mutex as long 
12e40 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  as the.** [SQLIT
12e50 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
12e60 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  US] configuratio
12e70 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e  n option is turn
12e80 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20  ed on (which.** 
12e90 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74  it is by default
12ea0 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74  ) and so the met
12eb0 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74  hods are automat
12ec0 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65  ically serialize
12ed0 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69  d..** However, i
12ee0 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
12ef0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64  _MEMSTATUS] is d
12f00 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68  isabled, then th
12f10 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f  e other.** metho
12f20 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  ds must be threa
12f30 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61  dsafe or else ma
12f40 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72  ke their own arr
12f50 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a  angements for.**
12f60 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a   serialization..
12f70 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
12f80 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78  l never invoke x
12f90 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e  Init() more than
12fa0 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e   once without an
12fb0 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20   intervening.** 
12fc0 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77  call to xShutdow
12fd0 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n()..*/.typedef 
12fe0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
12ff0 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  em_methods sqlit
13000 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a  e3_mem_methods;.
13010 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
13020 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76  em_methods {.  v
13030 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28  oid *(*xMalloc)(
13040 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a  int);         /*
13050 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
13060 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  on function */. 
13070 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76   void (*xFree)(v
13080 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
13090 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20  /* Free a prior 
130a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
130b0 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63  void *(*xRealloc
130c0 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f  )(void*,int);  /
130d0 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f  * Resize an allo
130e0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
130f0 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b  (*xSize)(void*);
13100 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65             /* Re
13110 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  turn the size of
13120 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
13130 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64  /.  int (*xRound
13140 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  up)(int);       
13150 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72     /* Round up r
13160 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61  equest size to a
13170 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a  llocation size *
13180 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29  /.  int (*xInit)
13190 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
131a0 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65     /* Initialize
131b0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
131c0 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
131d0 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  (*xShutdown)(voi
131e0 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69  d*);      /* Dei
131f0 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
13200 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
13210 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
13220 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ta;             
13230 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74     /* Argument t
13240 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53  o xInit() and xS
13250 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a  hutdown() */.};.
13260 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13270 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
13280 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ptions.** KEYWOR
13290 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69  DS: {configurati
132a0 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a  on option}.**.**
132b0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
132c0 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
132d0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
132e0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
132f0 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
13300 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
13310 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
13320 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
13330 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
13340 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
13350 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13360 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
13370 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
13380 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
13390 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
133a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
133b0 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
133c0 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
133d0 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
133e0 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
133f0 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
13400 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  3_config()] to m
13410 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
13420 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
13430 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
13440 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
13450 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
13460 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
13470 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
13480 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
13490 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
134a0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
134b0 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
134c0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
134d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
134e0 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74  NGLETHREAD]] <dt
134f0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
13500 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
13510 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
13520 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
13530 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
13540 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
13550 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
13560 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e  ing mode] to Sin
13570 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  gle-thread.  In 
13580 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
13590 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20  disables.** all 
135a0 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74  mutexing and put
135b0 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20  s SQLite into a 
135c0 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61  mode where it ca
135d0 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a  n only be used.*
135e0 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  * by a single th
135f0 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69  read.   ^If SQLi
13600 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
13610 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
13620 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
13630 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13640 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
13650 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
13660 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
13670 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ble to change th
13680 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
13690 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61  e] from its defa
136a0 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  ult.** value of 
136b0 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e  Single-thread an
136c0 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d so [sqlite3_co
136d0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
136e0 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urn .** [SQLITE_
136f0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
13700 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
13710 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
13720 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  READ.** configur
13730 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
13740 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13750 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
13760 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
13770 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
13780 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
13790 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
137a0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
137b0 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
137c0 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
137d0 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
137e0 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65  e] to Multi-thre
137f0 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
13800 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
13810 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
13820 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
13830 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
13840 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
13850 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
13860 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
13870 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
13880 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
13890 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
138a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
138b0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
138c0 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
138d0 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
138e0 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
138f0 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
13900 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
13910 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
13920 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
13930 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
13940 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d  wo threads attem
13950 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  pt to use the sa
13960 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  me.** [database 
13970 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74  connection] at t
13980 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e  he same time.  ^
13990 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
139a0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
139b0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
139c0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
139d0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
139e0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
139f0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
13a00 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
13a10 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65  t the Multi-thre
13a20 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
13a30 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
13a40 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
13a50 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
13a60 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
13a70 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
13a80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
13a90 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75  TITHREAD configu
13aa0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
13ab0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13ac0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
13ad0 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  IZED]] <dt>SQLIT
13ae0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
13af0 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
13b00 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
13b10 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
13b20 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
13b30 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
13b40 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
13b50 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] to Serialized.
13b60 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
13b70 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   this option ena
13b80 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
13b90 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
13ba0 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
13bb0 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
13bc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
13bd0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
13be0 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
13bf0 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
13c00 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
13c10 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
13c20 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
13c30 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
13c40 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
13c50 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
13c60 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
13c70 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
13c80 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
13c90 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
13ca0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
13cb0 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
13cc0 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
13cd0 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
13ce0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
13cf0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
13d00 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
13d10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
13d20 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
13d30 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
13d40 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66  ame time..** ^If
13d50 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
13d60 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
13d70 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
13d80 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
13d90 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
13da0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
13db0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
13dc0 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
13dd0 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b  the Serialized [
13de0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
13df0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
13e00 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
13e10 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
13e20 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
13e30 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
13e40 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
13e50 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ZED configuratio
13e60 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
13e70 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13e80 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  NFIG_MALLOC]] <d
13e90 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13ea0 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
13eb0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
13ec0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f  _CONFIG_MALLOC o
13ed0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
13ee0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
13ef0 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69  ich is .** a poi
13f00 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
13f10 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
13f20 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
13f30 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54   structure..** T
13f40 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
13f50 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
13f60 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
13f70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13f80 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
13f90 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
13fa0 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
13fb0 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
13fc0 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
13fd0 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
13fe0 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
13ff0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
14000 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
14010 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
14020 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
14030 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
14040 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
14050 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
14060 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
14070 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14080 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  TMALLOC]] <dt>SQ
14090 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
140a0 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
140b0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
140c0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
140d0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
140e0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
140f0 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
14100 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
14110 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
14120 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
14130 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20  ] structure..** 
14140 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
14150 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
14160 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
14170 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
14180 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
14190 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
141a0 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
141b0 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
141c0 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
141d0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
141e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
141f0 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
14200 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73  a wrapper that s
14210 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72  imulations memor
14220 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
14230 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b  lure or.** track
14240 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20  s memory usage, 
14250 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64  for example. </d
14260 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14270 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d  E_CONFIG_SMALL_M
14280 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
14290 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f  TE_CONFIG_SMALL_
142a0 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
142b0 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
142c0 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c  CONFIG_SMALL_MAL
142d0 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
142e0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
142f0 20 6f 66 0a 2a 2a 20 74 79 70 65 20 69 6e 74 2c   of.** type int,
14300 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
14310 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68  a boolean, which
14320 20 69 66 20 74 72 75 65 20 70 72 6f 76 69 64 65   if true provide
14330 73 20 61 20 68 69 6e 74 20 74 6f 0a 2a 2a 20 53  s a hint to.** S
14340 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 73 68  QLite that it sh
14350 6f 75 6c 64 20 61 76 6f 69 64 20 6c 61 72 67 65  ould avoid large
14360 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14370 6f 6e 73 20 69 66 20 70 6f 73 73 69 62 6c 65 2e  ons if possible.
14380 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
14390 72 75 6e 20 66 61 73 74 65 72 20 69 66 20 69 74  run faster if it
143a0 20 69 73 20 66 72 65 65 20 74 6f 20 6d 61 6b 65   is free to make
143b0 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c   large memory al
143c0 6c 6f 63 61 74 69 6f 6e 73 2c 0a 2a 2a 20 62 75  locations,.** bu
143d0 74 20 73 6f 6d 65 20 61 70 70 6c 69 63 61 74 69  t some applicati
143e0 6f 6e 20 6d 69 67 68 74 20 70 72 65 66 65 72 20  on might prefer 
143f0 74 6f 20 72 75 6e 20 73 6c 6f 77 65 72 20 69 6e  to run slower in
14400 20 65 78 63 68 61 6e 67 65 20 66 6f 72 0a 2a 2a   exchange for.**
14410 20 67 75 61 72 61 6e 74 65 65 73 20 61 62 6f 75   guarantees abou
14420 74 20 6d 65 6d 6f 72 79 20 66 72 61 67 6d 65 6e  t memory fragmen
14430 74 61 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20  tation that are 
14440 70 6f 73 73 69 62 6c 65 20 69 66 20 6c 61 72 67  possible if larg
14450 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  e.** allocations
14460 20 61 72 65 20 61 76 6f 69 64 65 64 2e 20 20 54   are avoided.  T
14470 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 72 6d  his hint is norm
14480 61 6c 6c 79 20 6f 66 66 2e 0a 2a 2a 20 3c 2f 64  ally off..** </d
14490 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
144a0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
144b0 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  US]] <dt>SQLITE_
144c0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
144d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
144e0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
144f0 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f  _MEMSTATUS optio
14500 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
14510 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
14520 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65  int,.** interpre
14530 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
14540 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20  , which enables 
14550 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
14560 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a  collection of.**
14570 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14580 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e  on statistics. ^
14590 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  (When memory all
145a0 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
145b0 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  cs are.** disabl
145c0 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ed, the followin
145d0 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  g SQLite interfa
145e0 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f  ces become non-o
145f0 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
14600 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
14610 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
14620 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
14630 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
14640 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
14650 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
14660 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
14670 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  t64()].**   <li>
14680 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
14690 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e  64()].**   </ul>
146a0 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c  )^.** ^Memory al
146b0 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
146c0 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  ics are enabled 
146d0 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73  by default unles
146e0 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  s SQLite is.** c
146f0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
14700 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
14710 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69  STATUS]=0 in whi
14720 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a  ch case memory.*
14730 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  * allocation sta
14740 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
14750 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
14760 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
14770 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14780 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51  SCRATCH]] <dt>SQ
14790 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
147a0 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
147b0 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   The SQLITE_CONF
147c0 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f  IG_SCRATCH optio
147d0 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75  n is no longer u
147e0 73 65 64 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  sed..** </dd>.**
147f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14800 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20  FIG_PAGECACHE]] 
14810 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14820 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
14830 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
14840 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
14850 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65  CACHE option spe
14860 63 69 66 69 65 73 20 61 20 6d 65 6d 6f 72 79 20  cifies a memory 
14870 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c  pool.** that SQL
14880 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20  ite can use for 
14890 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
148a0 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
148b0 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a   default page.**
148c0 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
148d0 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73  ation.  .** This
148e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
148f0 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70  ption is a no-op
14900 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
14910 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a  on-define page.*
14920 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
14930 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64  tation is loaded
14940 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
14950 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
14960 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72  2]..** ^There ar
14970 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
14980 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  s to SQLITE_CONF
14990 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20  IG_PAGECACHE: A 
149a0 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d  pointer to.** 8-
149b0 62 79 74 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d  byte aligned mem
149c0 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74 68 65 20  ory (pMem), the 
149d0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67  size of each pag
149e0 65 20 63 61 63 68 65 20 6c 69 6e 65 20 28 73 7a  e cache line (sz
149f0 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75  ),.** and the nu
14a00 6d 62 65 72 20 6f 66 20 63 61 63 68 65 20 6c 69  mber of cache li
14a10 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  nes (N)..** The 
14a20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
14a30 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
14a40 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
14a50 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
14a60 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
14a70 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 36  etween 512 and 6
14a80 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 20  5536) plus some 
14a90 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72 20  extra bytes for 
14aa0 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61  each.** page hea
14ab0 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65  der.  ^The numbe
14ac0 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65 73  r of extra bytes
14ad0 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20 70   needed by the p
14ae0 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61  age header.** ca
14af0 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
14b00 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f  using [SQLITE_CO
14b10 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
14b20 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61  Z]..** ^It is ha
14b30 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72  rmless, apart fr
14b40 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65  om the wasted me
14b50 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65  mory,.** for the
14b60 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f   sz parameter to
14b70 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
14b80 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65 20  necessary.  The 
14b90 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  pMem.** argument
14ba0 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
14bb0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
14bc0 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  r a pointer to a
14bd0 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
14be0 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  ned block of mem
14bf0 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ory of at least 
14c00 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68 65  sz*N bytes, othe
14c10 72 77 69 73 65 0a 2a 2a 20 73 75 62 73 65 71 75  rwise.** subsequ
14c20 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73 20  ent behavior is 
14c30 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57  undefined..** ^W
14c40 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20  hen pMem is not 
14c50 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
14c60 6c 20 73 74 72 69 76 65 20 74 6f 20 75 73 65 20  l strive to use 
14c70 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
14c80 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66  ded.** to satisf
14c90 79 20 70 61 67 65 20 63 61 63 68 65 20 6e 65 65  y page cache nee
14ca0 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b  ds, falling back
14cb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
14cc0 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70  loc()] if.** a p
14cd0 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 69  age cache line i
14ce0 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20 73 7a  s larger than sz
14cf0 20 62 79 74 65 73 20 6f 72 20 69 66 20 61 6c 6c   bytes or if all
14d00 20 6f 66 20 74 68 65 20 70 4d 65 6d 20 62 75 66   of the pMem buf
14d10 66 65 72 0a 2a 2a 20 69 73 20 65 78 68 61 75 73  fer.** is exhaus
14d20 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d  ted..** ^If pMem
14d30 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69   is NULL and N i
14d40 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
14d50 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
14d60 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65  onnection.** doe
14d70 73 20 61 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c  s an initial bul
14d80 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  k allocation for
14d90 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
14da0 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ry.** from [sqli
14db0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75  te3_malloc()] su
14dc0 66 66 69 63 69 65 6e 74 20 66 6f 72 20 4e 20 63  fficient for N c
14dd0 61 63 68 65 20 6c 69 6e 65 73 20 69 66 20 4e 20  ache lines if N 
14de0 69 73 20 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a  is positive or.*
14df0 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79 74  * of -1024*N byt
14e00 65 73 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74  es if N is negat
14e10 69 76 65 2c 20 2e 20 5e 49 66 20 61 64 64 69 74  ive, . ^If addit
14e20 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
14e30 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
14e40 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
14e50 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
14e60 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61  the initial.** a
14e70 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
14e80 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
14e90 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14ea0 5d 20 73 65 70 61 72 61 74 65 6c 79 20 66 6f 72  ] separately for
14eb0 20 65 61 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f   each.** additio
14ec0 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e 20  nal cache line. 
14ed0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14ee0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
14ef0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14f00 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a  NFIG_HEAP</dt>.*
14f10 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
14f20 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f  TE_CONFIG_HEAP o
14f30 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
14f40 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
14f50 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20  buffer .** that 
14f60 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
14f70 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
14f80 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c  ynamic memory al
14f90 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a  location needs.*
14fa0 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  * beyond those p
14fb0 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b  rovided for by [
14fc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
14fd0 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68  GECACHE]..** ^Th
14fe0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14ff0 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f  HEAP option is o
15000 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
15010 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
15020 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68  led.** with eith
15030 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
15040 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53  E_MEMSYS3] or [S
15050 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
15060 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e  SYS5] and return
15070 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  s.** [SQLITE_ERR
15080 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f  OR] if invoked o
15090 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68  therwise..** ^Th
150a0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
150b0 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
150c0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a  E_CONFIG_HEAP:.*
150d0 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  * An 8-byte alig
150e0 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ned pointer to t
150f0 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68  he memory,.** th
15100 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
15110 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
15120 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
15130 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
15140 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  on size..** ^If 
15150 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
15160 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
15170 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
15180 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
15190 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
151a0 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
151b0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
151c0 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
151d0 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
151e0 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
151f0 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
15200 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
15210 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e  NFIG_MALLOC].  ^
15220 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
15230 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
15240 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c  NULL then the al
15250 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
15260 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
15270 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
15280 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
15290 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
152a0 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
152b0 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
152c0 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
152d0 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
152e0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
152f0 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
15300 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
15310 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
15320 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
15330 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d  ..** The minimum
15340 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
15350 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a   is capped at 2*
15360 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20  *12. Reasonable 
15370 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68  values.** for th
15380 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
15390 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a  tion size are 2*
153a0 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e  *5 through 2**8.
153b0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
153c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
153d0 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
153e0 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
153f0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
15400 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
15410 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  EX option takes 
15420 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
15430 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20  t which is a.** 
15440 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
15450 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
15460 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
15470 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
15480 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
15490 20 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72   specifies alter
154a0 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
154b0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
154c0 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e  to be used.** in
154d0 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78   place the mutex
154e0 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
154f0 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20  into SQLite.)^  
15500 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
15510 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
15520 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
15530 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
15540 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20  hods] structure 
15550 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20  before the call 
15560 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
15570 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73  onfig()] returns
15580 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  . ^If SQLite is 
15590 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
155a0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
155b0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
155c0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
155d0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
155e0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
155f0 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
15600 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
15610 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
15620 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
15630 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
15640 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
15650 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
15660 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  IG_MUTEX configu
15670 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
15680 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
15690 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
156a0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
156b0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
156c0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
156d0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64  NFIG_GETMUTEX</d
156e0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
156f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
15700 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  ETMUTEX option t
15710 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
15720 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
15730 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
15740 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
15750 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
15760 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
15770 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
15780 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
15790 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
157a0 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
157b0 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
157c0 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
157d0 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
157e0 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
157f0 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
15800 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
15810 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
15820 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
15830 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
15840 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
15850 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
15860 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
15870 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
15880 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53  example.   ^If S
15890 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
158a0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
158b0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
158c0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
158d0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
158e0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
158f0 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
15900 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
15910 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
15920 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
15930 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
15940 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
15950 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
15960 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15970 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
15980 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
15990 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
159a0 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
159b0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
159c0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20  FIG_LOOKASIDE]] 
159d0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
159e0 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
159f0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
15a00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
15a10 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61  KASIDE option ta
15a20 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
15a30 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
15a40 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
15a50 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64  size of lookasid
15a60 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68  e memory on each
15a70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
15a80 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66  ction]..** The f
15a90 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
15aa0 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
15ab0 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
15ac0 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
15ad0 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65  he second is the
15ae0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
15af0 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f  ots allocated to
15b00 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
15b10 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28  onnection.)^  ^(
15b20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15b30 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20  OKASIDE.** sets 
15b40 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f  the <i>default</
15b50 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a  i> lookaside siz
15b60 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44  e. The [SQLITE_D
15b70 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
15b80 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20  E].** option to 
15b90 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
15ba0 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65  ig()] can be use
15bb0 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
15bc0 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e  lookaside.** con
15bd0 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e  figuration on in
15be0 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74  dividual connect
15bf0 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ions.)^ </dd>.**
15c00 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15c10 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64  FIG_PCACHE2]] <d
15c20 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15c30 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
15c40 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
15c50 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
15c60 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
15c70 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
15c80 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70  which is .** a p
15c90 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
15ca0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
15cb0 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
15cc0 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
15cd0 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74  ifies.** the int
15ce0 65 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74  erface to a cust
15cf0 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
15d00 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a  plementation.)^.
15d10 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ** ^SQLite makes
15d20 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b   a copy of the [
15d30 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
15d40 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
15d50 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15d60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15d70 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
15d80 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
15d90 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
15da0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
15db0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15dc0 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  2 option takes a
15dd0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
15de0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
15df0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
15e00 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
15e10 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
15e20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
15e30 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20  .** the current 
15e40 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
15e50 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
15e60 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
15e70 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15e80 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
15e90 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15ea0 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
15eb0 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d> The SQLITE_CO
15ec0 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
15ed0 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
15ee0 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a  gure the SQLite.
15ef0 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72  ** global [error
15f00 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20   log]..** (^The 
15f10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15f20 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
15f30 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
15f40 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
15f50 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
15f60 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
15f70 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
15f80 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
15f90 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
15fa0 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
15fb0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
15fc0 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
15fd0 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
15fe0 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
15ff0 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
16000 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
16010 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
16020 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
16030 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
16040 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
16050 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
16060 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
16070 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
16080 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
16090 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
160a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
160b0 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
160c0 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
160d0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
160e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
160f0 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
16100 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
16110 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
16120 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
16130 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
16140 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
16150 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
16160 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
16170 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
16180 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
16190 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
161a0 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
161b0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
161c0 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
161d0 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
161e0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
161f0 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
16200 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
16210 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
16220 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
16230 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
16240 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
16250 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
16260 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
16270 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
16280 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
16290 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
162a0 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
162b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
162c0 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
162d0 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
162e0 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
162f0 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
16300 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
16310 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
16320 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
16330 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
16340 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
16350 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16360 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
16370 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
16380 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53  I.** <dd>^(The S
16390 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
163a0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
163b0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
163c0 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20  of type int..** 
163d0 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  If non-zero, the
163e0 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  n URI handling i
163f0 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
16400 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
16410 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a  eter is zero,.**
16420 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
16430 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ng is globally d
16440 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55  isabled.)^ ^If U
16450 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
16460 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c  lobally.** enabl
16470 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65  ed, all filename
16480 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
16490 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
164a0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
164b0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
164c0 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73  pen16()] or.** s
164d0 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
164e0 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d   of [ATTACH] com
164f0 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70  mands are interp
16500 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72  reted as URIs, r
16510 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20  egardless.** of 
16520 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
16530 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
16540 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74  URI] flag is set
16550 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
16560 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
16570 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20   is opened. ^If 
16580 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  it is globally d
16590 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d  isabled, filenam
165a0 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69  es are.** only i
165b0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
165c0 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45  Is if the SQLITE
165d0 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69  _OPEN_URI flag i
165e0 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a  s set when the.*
165f0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
16600 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
16610 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55   ^(By default, U
16620 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
16630 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62  lobally.** disab
16640 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74  led. The default
16650 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68   value may be ch
16660 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69  anged by compili
16670 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ng with the.** [
16680 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
16690 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29  symbol defined.)
166a0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
166b0 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
166c0 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64  _INDEX_SCAN]] <d
166d0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
166e0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
166f0 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  CAN.** <dd>^The 
16700 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
16710 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
16720 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  N option takes a
16730 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a   single integer.
16740 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ** argument whic
16750 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
16760 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e   as a boolean in
16770 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65   order to enable
16780 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   or disable.** t
16790 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
167a0 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
167b0 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20  ull table scans 
167c0 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74  in the query opt
167d0 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  imizer..** ^The 
167e0 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
167f0 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
16800 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
16810 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49  ALLOW_COVERING_I
16820 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69  NDEX_SCAN] compi
16830 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
16840 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66  or is "on".** if
16850 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
16860 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69  me option is omi
16870 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69  tted..** The abi
16880 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20  lity to disable 
16890 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
168a0 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
168b0 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
168c0 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73  .** is because s
168d0 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ome incorrectly 
168e0 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70  coded legacy app
168f0 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lications might 
16900 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  malfunction.** w
16910 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  hen the optimiza
16920 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
16930 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20    Providing the 
16940 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69  ability to.** di
16950 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69  sable the optimi
16960 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68  zation allows th
16970 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61  e older, buggy a
16980 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
16990 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f  to work.** witho
169a0 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77  ut change even w
169b0 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f  ith newer versio
169c0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
169d0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
169e0 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53  FIG_PCACHE]] [[S
169f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16a00 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  PCACHE]].** <dt>
16a10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
16a20 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE and SQLITE_
16a30 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
16a40 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
16a50 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
16a60 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
16a70 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
16a80 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
16a90 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
16aa0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
16ab0 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
16ac0 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
16ad0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
16ae0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
16af0 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  OG]].** <dt>SQLI
16b00 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
16b10 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
16b20 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
16b30 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20  lable if sqlite 
16b40 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
16b50 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
16b60 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70  ENABLE_SQLLOG] p
16b70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
16b80 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20  ro defined. The 
16b90 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73  first argument s
16ba0 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f  hould.** be a po
16bb0 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74  inter to a funct
16bc0 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64  ion of type void
16bd0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
16be0 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  3*,const char*, 
16bf0 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  int)..** The sec
16c00 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66  ond should be of
16c10 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54   type (void*). T
16c20 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
16c30 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69  nvoked by the li
16c40 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65  brary.** in thre
16c50 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75  e separate circu
16c60 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69  mstances, identi
16c70 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75  fied by the valu
16c80 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  e passed as the.
16c90 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
16ca0 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72  ter. If the four
16cb0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
16cc0 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  0, then the data
16cd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
16ce0 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
16cf0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
16d00 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f   has just been o
16d10 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64  pened. The third
16d20 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69   argument.** poi
16d30 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20  nts to a buffer 
16d40 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
16d50 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20  ame of the main 
16d60 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49  database file. I
16d70 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
16d80 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20  parameter is 1, 
16d90 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  then the SQL sta
16da0 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20  tement that the 
16db0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a  third parameter.
16dc0 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73  ** points to has
16dd0 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75   just been execu
16de0 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  ted. Or, if the 
16df0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
16e00 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74   is 2, then.** t
16e10 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  he connection be
16e20 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68  ing passed as th
16e30 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
16e40 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73  er is being clos
16e50 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ed. The.** third
16e60 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61   parameter is pa
16e70 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69  ssed NULL In thi
16e80 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d  s case.  An exam
16e90 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ple of using thi
16ea0 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  s.** configurati
16eb0 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  on option can be
16ec0 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65   seen in the "te
16ed0 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75  st_sqllog.c" sou
16ee0 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74  rce file in.** t
16ef0 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c  he canonical SQL
16f00 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ite source tree.
16f10 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
16f20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
16f30 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  _SIZE]].** <dt>S
16f40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
16f50 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53  P_SIZE.** <dd>^S
16f60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
16f70 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f  P_SIZE takes two
16f80 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
16f90 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20  (sqlite3_int64) 
16fa0 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61  values.** that a
16fb0 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  re the default m
16fc0 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28  map size limit (
16fd0 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  the default sett
16fe0 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47  ing for.** [PRAG
16ff0 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61  MA mmap_size]) a
17000 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61  nd the maximum a
17010 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
17020 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20   limit..** ^The 
17030 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
17040 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
17050 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61  n by each databa
17060 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73  se connection us
17070 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68  ing.** either th
17080 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  e [PRAGMA mmap_s
17090 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72  ize] command, or
170a0 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   by using the.**
170b0 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
170c0 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
170d0 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d  ontrol.  ^(The m
170e0 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
170f0 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c  map size.** will
17100 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75   be silently tru
17110 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73  ncated if necess
17120 61 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64  ary so that it d
17130 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74  oes not exceed t
17140 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  he.** compile-ti
17150 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20  me maximum mmap 
17160 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a  size set by the.
17170 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d  ** [SQLITE_MAX_M
17180 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c  MAP_SIZE] compil
17190 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e  e-time option.)^
171a0 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61  .** ^If either a
171b0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
171c0 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69  option is negati
171d0 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72  ve, then that ar
171e0 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61  gument is.** cha
171f0 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70  nged to its comp
17200 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74  ile-time default
17210 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
17220 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
17230 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  APSIZE]].** <dt>
17240 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
17250 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20  N32_HEAPSIZE.** 
17260 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
17270 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
17280 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20  PSIZE option is 
17290 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
172a0 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  f SQLite is.** c
172b0 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64  ompiled for Wind
172c0 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51  ows with the [SQ
172d0 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f  LITE_WIN32_MALLO
172e0 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  C] pre-processor
172f0 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65   macro.** define
17300 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  d. ^SQLITE_CONFI
17310 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
17320 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20   takes a 32-bit 
17330 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
17340 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73   value.** that s
17350 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78  pecifies the max
17360 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65  imum size of the
17370 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a   created heap..*
17380 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
17390 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
173a0 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  Z]].** <dt>SQLIT
173b0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
173c0 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68  HDRSZ.** <dd>^Th
173d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
173e0 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74  PCACHE_HDRSZ opt
173f0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
17400 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
17410 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
17420 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
17430 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f   and writes into
17440 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68   that integer th
17450 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
17460 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70  a.** bytes per p
17470 61 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72  age required for
17480 20 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53   each page in [S
17490 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
174a0 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20  ECACHE]..** The 
174b0 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20  amount of extra 
174c0 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63  space required c
174d0 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64  an change depend
174e0 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  ing on the compi
174f0 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70  ler,.** target p
17500 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c  latform, and SQL
17510 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a  ite version..**.
17520 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
17530 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64  IG_PMASZ]].** <d
17540 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
17550 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68  PMASZ.** <dd>^Th
17560 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17570 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b  PMASZ option tak
17580 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61  es a single para
17590 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  meter which.** i
175a0 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e  s an unsigned in
175b0 74 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74  teger and sets t
175c0 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20  he "Minimum PMA 
175d0 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75  Size" for the mu
175e0 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73  ltithreaded.** s
175f0 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e  orter to that in
17600 74 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61  teger.  The defa
17610 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20  ult minimum PMA 
17620 53 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74  Size is set by t
17630 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f  he.** [SQLITE_SO
17640 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70  RTER_PMASZ] comp
17650 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
17660 20 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72    New threads ar
17670 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f  e launched.** to
17680 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20   help with sort 
17690 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20  operations when 
176a0 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f  multithreaded so
176b0 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62  rting.** is enab
176c0 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b  led (using the [
176d0 50 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20  PRAGMA threads] 
176e0 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65  command) and the
176f0 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65   amount of conte
17700 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74  nt.** to be sort
17710 65 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70  ed exceeds the p
17720 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74  age size times t
17730 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68  he minimum of th
17740 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63  e.** [PRAGMA cac
17750 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67  he_size] setting
17760 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e   and this value.
17770 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
17780 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f  CONFIG_STMTJRNL_
17790 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  SPILL]].** <dt>S
177a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
177b0 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c  TJRNL_SPILL.** <
177c0 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
177d0 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53  ONFIG_STMTJRNL_S
177e0 50 49 4c 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65  PILL option take
177f0 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
17800 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 62 65  eter which.** be
17810 63 6f 6d 65 73 20 74 68 65 20 5b 73 74 61 74 65  comes the [state
17820 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70  ment journal] sp
17830 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65  ill-to-disk thre
17840 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61  shold.  .** [Sta
17850 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d  tement journals]
17860 20 61 72 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d   are held in mem
17870 6f 72 79 20 75 6e 74 69 6c 20 74 68 65 69 72 20  ory until their 
17880 73 69 7a 65 20 28 69 6e 20 62 79 74 65 73 29 0a  size (in bytes).
17890 2a 2a 20 65 78 63 65 65 64 73 20 74 68 69 73 20  ** exceeds this 
178a0 74 68 72 65 73 68 6f 6c 64 2c 20 61 74 20 77 68  threshold, at wh
178b0 69 63 68 20 70 6f 69 6e 74 20 74 68 65 79 20 61  ich point they a
178c0 72 65 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  re written to di
178d0 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65  sk..** Or if the
178e0 20 74 68 72 65 73 68 6f 6c 64 20 69 73 20 2d 31   threshold is -1
178f0 2c 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72  , statement jour
17900 6e 61 6c 73 20 61 72 65 20 61 6c 77 61 79 73 20  nals are always 
17910 68 65 6c 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76  held.** exclusiv
17920 65 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a  ely in memory..*
17930 2a 20 53 69 6e 63 65 20 6d 61 6e 79 20 73 74 61  * Since many sta
17940 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20  tement journals 
17950 6e 65 76 65 72 20 62 65 63 6f 6d 65 20 6c 61 72  never become lar
17960 67 65 2c 20 73 65 74 74 69 6e 67 20 74 68 65 20  ge, setting the 
17970 73 70 69 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f  spill.** thresho
17980 6c 64 20 74 6f 20 61 20 76 61 6c 75 65 20 73 75  ld to a value su
17990 63 68 20 61 73 20 36 34 4b 69 42 20 63 61 6e 20  ch as 64KiB can 
179a0 67 72 65 61 74 6c 79 20 72 65 64 75 63 65 20 74  greatly reduce t
179b0 68 65 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20  he amount of.** 
179c0 49 2f 4f 20 72 65 71 75 69 72 65 64 20 74 6f 20  I/O required to 
179d0 73 75 70 70 6f 72 74 20 73 74 61 74 65 6d 65 6e  support statemen
179e0 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  t rollback..** T
179f0 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
17a00 20 66 6f 72 20 74 68 69 73 20 73 65 74 74 69 6e   for this settin
17a10 67 20 69 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  g is controlled 
17a20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
17a30 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  E_STMTJRNL_SPILL
17a40 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
17a50 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  ption..** </dl>.
17a60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17a70 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
17a80 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
17a90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17aa0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
17ab0 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
17ac0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
17ad0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
17ae0 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
17af0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
17b00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
17b10 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
17b20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
17b30 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
17b40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
17b50 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
17b60 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
17b70 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
17b80 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17b90 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
17ba0 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
17bb0 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
17bc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
17bd0 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
17be0 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
17bf0 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
17c00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
17c10 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
17c20 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
17c30 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
17c40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17c50 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
17c60 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
17c70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17c80 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
17c90 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
17ca0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
17cb0 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
17cc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
17cd0 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
17ce0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
17cf0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70  methods* */./* p
17d00 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45  reviously SQLITE
17d10 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
17d20 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e  OC 12 which is n
17d30 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23  ow unused. */ .#
17d40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17d50 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
17d60 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74    13  /* int int
17d70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17d80 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
17d90 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f         14  /* no
17da0 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
17db0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
17dc0 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a  PCACHE    15  /*
17dd0 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
17de0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17df0 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20  LOG          16 
17e00 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a   /* xFunc, void*
17e10 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17e20 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20  TE_CONFIG_URI   
17e30 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e         17  /* in
17e40 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
17e50 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
17e60 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73  E2      18  /* s
17e70 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
17e80 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
17e90 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17ea0 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39  _GETPCACHE2   19
17eb0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
17ec0 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
17ed0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17ee0 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
17ef0 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f  INDEX_SCAN 20  /
17f00 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
17f10 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
17f20 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20  QLLOG       21  
17f30 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64  /* xSqllog, void
17f40 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
17f50 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
17f60 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73  SIZE    22  /* s
17f70 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71  qlite3_int64, sq
17f80 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23  lite3_int64 */.#
17f90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17fa0 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
17fb0 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20  IZE      23  /* 
17fc0 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65  int nByte */.#de
17fd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17fe0 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20  IG_PCACHE_HDRSZ 
17ff0 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e         24  /* in
18000 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e  t *psz */.#defin
18010 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18020 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20  PMASZ           
18030 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67      25  /* unsig
18040 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f  ned int szPma */
18050 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18060 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f  CONFIG_STMTJRNL_
18070 53 50 49 4c 4c 20 20 20 20 20 20 32 36 20 20 2f  SPILL      26  /
18080 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23  * int nByte */.#
18090 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
180a0 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f  NFIG_SMALL_MALLO
180b0 43 20 20 20 20 20 20 20 20 32 37 20 20 2f 2a 20  C        27  /* 
180c0 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 0a 2f 2a 0a 2a  boolean */../*.*
180d0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
180e0 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
180f0 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
18100 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
18110 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
18120 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
18130 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
18140 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
18150 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
18160 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
18170 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
18180 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
18190 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
181a0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
181b0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
181c0 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
181d0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
181e0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
181f0 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
18200 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
18210 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
18220 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
18230 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
18240 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
18250 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
18260 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
18270 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
18280 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
18290 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
182a0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
182b0 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
182c0 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
182d0 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
182e0 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
182f0 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
18300 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
18310 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
18320 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
18330 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
18340 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
18350 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
18360 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
18370 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
18380 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
18390 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
183a0 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
183b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
183c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
183d0 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
183e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
183f0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
18400 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
18410 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
18420 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
18430 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
18440 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
18450 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
18460 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
18470 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
18480 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
18490 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
184a0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
184b0 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
184c0 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
184d0 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
184e0 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
184f0 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
18500 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
18510 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
18520 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
18530 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
18540 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
18550 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
18560 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
18570 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
18580 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
18590 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
185a0 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
185b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
185c0 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
185d0 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
185e0 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
185f0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
18600 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
18610 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
18620 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
18630 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
18640 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
18650 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
18660 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
18670 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
18680 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
18690 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
186a0 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
186b0 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
186c0 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
186d0 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
186e0 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
186f0 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
18700 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
18710 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
18720 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
18730 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
18740 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
18750 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
18760 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
18770 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
18780 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
18790 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
187a0 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
187b0 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
187c0 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
187d0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
187e0 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
187f0 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
18800 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
18810 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
18820 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
18830 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
18840 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
18850 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
18860 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
18870 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
18880 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
18890 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  )^</dd>.**.** <d
188a0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
188b0 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64  G_ENABLE_FKEY</d
188c0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
188d0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
188e0 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
188f0 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65  able the enforce
18900 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65  ment of.** [fore
18910 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
18920 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f  nts].  There sho
18930 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
18940 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
18950 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
18960 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
18970 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
18980 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e  to disable FK en
18990 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f  forcement,.** po
189a0 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
189b0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
189c0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
189d0 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  eave FK enforcem
189e0 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ent.** unchanged
189f0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
18a00 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
18a10 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
18a20 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
18a30 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
18a40 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
18a50 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63  hether FK enforc
18a60 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20  ement is off or 
18a70 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  on.** following 
18a80 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
18a90 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18aa0 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
18ab0 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
18ac0 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20  ich case the FK 
18ad0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74  enforcement sett
18ae0 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
18af0 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
18b00 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
18b10 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
18b20 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a  _TRIGGER</dt>.**
18b30 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
18b40 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
18b50 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
18b60 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
18b70 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20  | triggers]..** 
18b80 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
18b90 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
18ba0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
18bb0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
18bc0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
18bd0 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
18be0 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a  ble triggers,.**
18bf0 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
18c00 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20  ble triggers or 
18c10 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
18c20 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e  e the setting un
18c30 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
18c40 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18c50 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
18c60 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
18c70 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
18c80 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
18c90 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
18ca0 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73  triggers are dis
18cb0 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
18cc0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
18cd0 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
18ce0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
18cf0 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
18d00 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
18d10 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67  h case the trigg
18d20 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  er setting is no
18d30 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
18d40 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
18d50 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
18d60 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b  _ENABLE_FTS3_TOK
18d70 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  ENIZER</dt>.** <
18d80 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
18d90 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
18da0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
18db0 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a 2a  e two-argument.*
18dc0 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  * version of the
18dd0 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72   [fts3_tokenizer
18de0 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69  ()] function whi
18df0 63 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 68  ch is part of th
18e00 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c  e.** [FTS3] full
18e10 2d 74 65 78 74 20 73 65 61 72 63 68 20 65 6e 67  -text search eng
18e20 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a  ine extension..*
18e30 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
18e40 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
18e50 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
18e60 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18e70 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
18e80 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
18e90 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e  sable fts3_token
18ea0 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73  izer() or.** pos
18eb0 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
18ec0 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29  fts3_tokenizer()
18ed0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
18ee0 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
18ef0 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a  g.** unchanged..
18f00 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
18f10 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
18f20 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
18f30 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
18f40 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
18f50 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
18f60 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65  hether fts3_toke
18f70 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  nizer is disable
18f80 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
18f90 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
18fa0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
18fb0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
18fc0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
18fd0 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
18fe0 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69  se the new setti
18ff0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
19000 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
19010 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
19020 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
19030 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f  LOAD_EXTENSION</
19040 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
19050 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
19060 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
19070 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  sable the [sqlit
19080 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
19090 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  n()].** interfac
190a0 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79 20  e independently 
190b0 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74  of the [load_ext
190c0 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66 75  ension()] SQL fu
190d0 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b  nction..** The [
190e0 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
190f0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
19100 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72 20   API enables or 
19110 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74 68  disables both th
19120 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c 69  e.** C-API [sqli
19130 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
19140 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53 51  on()] and the SQ
19150 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64  L function [load
19160 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a  _extension()]..*
19170 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
19180 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
19190 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57   arguments..** W
191a0 68 65 6e 20 74 68 65 20 66 69 72 73 74 20 61 72  hen the first ar
191b0 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 69  gument to this i
191c0 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c 20 74  nterface is 1, t
191d0 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d 41  hen only the C-A
191e0 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65 64  PI is.** enabled
191f0 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e   and the SQL fun
19200 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64 69  ction remains di
19210 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65 20  sabled.  If the 
19220 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
19230 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66  o.** this interf
19240 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20 62  ace is 0, then b
19250 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20 61 6e  oth the C-API an
19260 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  d the SQL functi
19270 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64 2e  on are disabled.
19280 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73 74  .** If the first
19290 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31 2c   argument is -1,
192a0 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 73   then no changes
192b0 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74 61   are made to sta
192c0 74 65 20 6f 66 20 65 69 74 68 65 72 20 74 68 65  te of either the
192d0 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68 65  .** C-API or the
192e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   SQL function..*
192f0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
19300 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
19310 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
19320 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
19330 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
19340 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
19350 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 6c  ether [sqlite3_l
19360 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
19370 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73   interface.** is
19380 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
19390 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  bled following t
193a0 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
193b0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
193c0 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c 4c  may.** be a NULL
193d0 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68 69   pointer, in whi
193e0 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20  ch case the new 
193f0 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
19400 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a 2a  eported back..**
19410 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
19420 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
19430 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74 3e  _MAINDBNAME</dt>
19440 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
19450 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
19460 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61 6d 65   change the name
19470 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22 20 64   of the "main" d
19480 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68 65 6d  atabase.** schem
19490 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20 61 72  a.  ^The sole ar
194a0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
194b0 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74 61 6e  ter to a constan
194c0 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a  t UTF8 string.**
194d0 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 63 6f   which will beco
194e0 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68 65 6d  me the new schem
194f0 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65 20  a name in place 
19500 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51 4c  of "main".  ^SQL
19510 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ite.** does not 
19520 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74  make a copy of t
19530 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63 68 65  he new main sche
19540 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c 20  ma name string, 
19550 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  so the applicati
19560 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72  on.** must ensur
19570 65 20 74 68 61 74 20 74 68 65 20 61 72 67 75 6d  e that the argum
19580 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ent passed into 
19590 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20 6f 70  this DBCONFIG op
195a0 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67 65  tion is unchange
195b0 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65 72  d.** until after
195c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
195d0 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
195e0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
195f0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
19600 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43  FIG_NO_CKPT_ON_C
19610 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LOSE</dt>.** <dd
19620 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20  > Usually, when 
19630 61 20 64 61 74 61 62 61 73 65 20 69 6e 20 77 61  a database in wa
19640 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73 65 64  l mode is closed
19650 20 6f 72 20 64 65 74 61 63 68 65 64 20 66 72 6f   or detached fro
19660 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  m a .** database
19670 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74 65 20   handle, SQLite 
19680 63 68 65 63 6b 73 20 69 66 20 74 68 69 73 20 77  checks if this w
19690 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20 74 68  ill mean that th
196a0 65 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f 20 0a  ere are now no .
196b0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61  ** connections a
196c0 74 20 61 6c 6c 20 74 6f 20 74 68 65 20 64 61 74  t all to the dat
196d0 61 62 61 73 65 2e 20 49 66 20 73 6f 2c 20 69 74  abase. If so, it
196e0 20 70 65 72 66 6f 72 6d 73 20 61 20 63 68 65 63   performs a chec
196f0 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65 72 61  kpoint .** opera
19700 74 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c 6f 73  tion before clos
19710 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  ing the connecti
19720 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  on. This option 
19730 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 0a 2a  may be used to.*
19740 2a 20 6f 76 65 72 72 69 64 65 20 74 68 69 73 20  * override this 
19750 62 65 68 61 76 69 6f 75 72 2e 20 54 68 65 20 66  behaviour. The f
19760 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 70  irst parameter p
19770 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f 70  assed to this op
19780 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 61 6e  eration.** is an
19790 20 69 6e 74 65 67 65 72 20 2d 20 70 6f 73 69 74   integer - posit
197a0 69 76 65 20 74 6f 20 64 69 73 61 62 6c 65 20 63  ive to disable c
197b0 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c  heckpoints-on-cl
197c0 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28 74 68  ose, or zero (th
197d0 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20 74 6f  e.** default) to
197e0 20 65 6e 61 62 6c 65 20 74 68 65 6d 2c 20 61 6e   enable them, an
197f0 64 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  d negative to le
19800 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20  ave the setting 
19810 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68  unchanged..** Th
19820 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
19830 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
19840 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
19850 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73 20 77   into which is w
19860 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
19870 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
19880 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e  r checkpoints-on
19890 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65 20 62  -close.** have b
198a0 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d 20 30  een disabled - 0
198b0 20 69 66 20 74 68 65 79 20 61 72 65 20 6e 6f 74   if they are not
198c0 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69 66 20   disabled, 1 if 
198d0 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c 2f 64  they are..** </d
198e0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
198f0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
19900 42 4c 45 5f 51 50 53 47 3c 2f 64 74 3e 0a 2a 2a  BLE_QPSG</dt>.**
19910 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54   <dd>^(The SQLIT
19920 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
19930 45 5f 51 50 53 47 20 6f 70 74 69 6f 6e 20 61 63  E_QPSG option ac
19940 74 69 76 61 74 65 73 20 6f 72 20 64 65 61 63 74  tivates or deact
19950 69 76 61 74 65 73 0a 2a 2a 20 74 68 65 20 5b 71  ivates.** the [q
19960 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 73 74 61  uery planner sta
19970 62 69 6c 69 74 79 20 67 75 61 72 61 6e 74 65 65  bility guarantee
19980 5d 20 28 51 50 53 47 29 2e 20 20 57 68 65 6e 20  ] (QPSG).  When 
19990 74 68 65 20 51 50 53 47 20 69 73 20 61 63 74 69  the QPSG is acti
199a0 76 65 2c 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 20  ve,.** a single 
199b0 53 51 4c 20 71 75 65 72 79 20 73 74 61 74 65 6d  SQL query statem
199c0 65 6e 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ent will always 
199d0 75 73 65 20 74 68 65 20 73 61 6d 65 20 61 6c 67  use the same alg
199e0 6f 72 69 74 68 6d 20 72 65 67 61 72 64 6c 65 73  orithm regardles
199f0 73 0a 2a 2a 20 6f 66 20 76 61 6c 75 65 73 20 6f  s.** of values o
19a00 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  f [bound paramet
19a10 65 72 73 5d 2e 29 5e 20 54 68 65 20 51 50 53 47  ers].)^ The QPSG
19a20 20 64 69 73 61 62 6c 65 73 20 73 6f 6d 65 20 71   disables some q
19a30 75 65 72 79 20 6f 70 74 69 6d 69 7a 61 74 69 6f  uery optimizatio
19a40 6e 73 0a 2a 2a 20 74 68 61 74 20 6c 6f 6f 6b 20  ns.** that look 
19a50 61 74 20 74 68 65 20 76 61 6c 75 65 73 20 6f 66  at the values of
19a60 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72   bound parameter
19a70 73 2c 20 77 68 69 63 68 20 63 61 6e 20 6d 61 6b  s, which can mak
19a80 65 20 73 6f 6d 65 20 71 75 65 72 69 65 73 0a 2a  e some queries.*
19a90 2a 20 73 6c 6f 77 65 72 2e 20 20 42 75 74 20 74  * slower.  But t
19aa0 68 65 20 51 50 53 47 20 68 61 73 20 74 68 65 20  he QPSG has the 
19ab0 61 64 76 61 6e 74 61 67 65 20 6f 66 20 6d 6f 72  advantage of mor
19ac0 65 20 70 72 65 64 69 63 74 61 62 6c 65 20 62 65  e predictable be
19ad0 68 61 76 69 6f 72 2e 20 20 57 69 74 68 0a 2a 2a  havior.  With.**
19ae0 20 74 68 65 20 51 50 53 47 20 61 63 74 69 76 65   the QPSG active
19af0 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  , SQLite will al
19b00 77 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d  ways use the sam
19b10 65 20 71 75 65 72 79 20 70 6c 61 6e 20 69 6e 20  e query plan in 
19b20 74 68 65 20 66 69 65 6c 64 20 61 73 0a 2a 2a 20  the field as.** 
19b30 77 61 73 20 75 73 65 64 20 64 75 72 69 6e 67 20  was used during 
19b40 74 65 73 74 69 6e 67 20 69 6e 20 74 68 65 20 6c  testing in the l
19b50 61 62 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ab..** The first
19b60 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
19b70 73 20 73 65 74 74 69 6e 67 20 69 73 20 61 6e 20  s setting is an 
19b80 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
19b90 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 0a 2a   0 to disable .*
19ba0 2a 20 74 68 65 20 51 50 53 47 2c 20 70 6f 73 69  * the QPSG, posi
19bb0 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 51  tive to enable Q
19bc0 50 53 47 2c 20 6f 72 20 6e 65 67 61 74 69 76 65  PSG, or negative
19bd0 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
19be0 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67  tting.** unchang
19bf0 65 64 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70  ed. The second p
19c00 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
19c10 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
19c20 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
19c30 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
19c40 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
19c50 77 68 65 74 68 65 72 20 74 68 65 20 51 50 53 47  whether the QPSG
19c60 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20   is disabled or 
19c70 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
19c80 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 0a  wing this call..
19c90 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
19ca0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
19cb0 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50 3c 2f  IG_TRIGGER_EQP</
19cc0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 42 79 20 64  dt>.** <dd> By d
19cd0 65 66 61 75 6c 74 2c 20 74 68 65 20 6f 75 74 70  efault, the outp
19ce0 75 74 20 6f 66 20 45 58 50 4c 41 49 4e 20 51 55  ut of EXPLAIN QU
19cf0 45 52 59 20 50 4c 41 4e 20 63 6f 6d 6d 61 6e 64  ERY PLAN command
19d00 73 20 64 6f 65 73 20 6e 6f 74 20 0a 2a 2a 20 69  s does not .** i
19d10 6e 63 6c 75 64 65 20 6f 75 74 70 75 74 20 66 6f  nclude output fo
19d20 72 20 61 6e 79 20 6f 70 65 72 61 74 69 6f 6e 73  r any operations
19d30 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 72   performed by tr
19d40 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20  igger programs. 
19d50 54 68 69 73 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69  This.** option i
19d60 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
19d70 20 63 6c 65 61 72 20 28 74 68 65 20 64 65 66 61   clear (the defa
19d80 75 6c 74 29 20 61 20 66 6c 61 67 20 74 68 61 74  ult) a flag that
19d90 20 67 6f 76 65 72 6e 73 20 74 68 69 73 0a 2a 2a   governs this.**
19da0 20 62 65 68 61 76 69 6f 72 2e 20 54 68 65 20 66   behavior. The f
19db0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 70  irst parameter p
19dc0 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f 70  assed to this op
19dd0 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 69 6e  eration is an in
19de0 74 65 67 65 72 20 2d 0a 2a 2a 20 70 6f 73 69 74  teger -.** posit
19df0 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 6f 75  ive to enable ou
19e00 74 70 75 74 20 66 6f 72 20 74 72 69 67 67 65 72  tput for trigger
19e10 20 70 72 6f 67 72 61 6d 73 2c 20 6f 72 20 7a 65   programs, or ze
19e20 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20 69 74  ro to disable it
19e30 2c 0a 2a 2a 20 6f 72 20 6e 65 67 61 74 69 76 65  ,.** or negative
19e40 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
19e50 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e  tting unchanged.
19e60 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
19e70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
19e80 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
19e90 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 20 69  ger into which i
19ea0 73 20 77 72 69 74 74 65 6e 20 0a 2a 2a 20 30 20  s written .** 0 
19eb0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
19ec0 20 77 68 65 74 68 65 72 20 6f 75 74 70 75 74 2d   whether output-
19ed0 66 6f 72 2d 74 72 69 67 67 65 72 73 20 68 61 73  for-triggers has
19ee0 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d   been disabled -
19ef0 20 30 20 69 66 20 0a 2a 2a 20 69 74 20 69 73 20   0 if .** it is 
19f00 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20  not disabled, 1 
19f10 69 66 20 69 74 20 69 73 2e 20 20 0a 2a 2a 20 3c  if it is.  .** <
19f20 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  /dd>.** </dl>.*/
19f30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19f40 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e  DBCONFIG_MAINDBN
19f50 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 31  AME            1
19f60 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63 68 61  000 /* const cha
19f70 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  r* */.#define SQ
19f80 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
19f90 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 20 20  OKASIDE         
19fa0 20 20 20 20 31 30 30 31 20 2f 2a 20 76 6f 69 64      1001 /* void
19fb0 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
19fc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
19fd0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
19fe0 20 20 20 20 20 20 20 20 20 20 20 31 30 30 32 20             1002 
19ff0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
1a000 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
1a010 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
1a020 49 47 47 45 52 20 20 20 20 20 20 20 20 31 30 30  IGGER        100
1a030 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  3 /* int int* */
1a040 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a050 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
1a060 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20 31  FTS3_TOKENIZER 1
1a070 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  004 /* int int* 
1a080 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a090 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
1a0a0 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e  E_LOAD_EXTENSION
1a0b0 20 31 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e 74   1005 /* int int
1a0c0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
1a0d0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f  ITE_DBCONFIG_NO_
1a0e0 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20 20  CKPT_ON_CLOSE   
1a0f0 20 20 20 31 30 30 36 20 2f 2a 20 69 6e 74 20 69     1006 /* int i
1a100 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
1a110 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
1a120 4e 41 42 4c 45 5f 51 50 53 47 20 20 20 20 20 20  NABLE_QPSG      
1a130 20 20 20 20 20 31 30 30 37 20 2f 2a 20 69 6e 74       1007 /* int
1a140 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
1a150 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1a160 5f 54 52 49 47 47 45 52 5f 45 51 50 20 20 20 20  _TRIGGER_EQP    
1a170 20 20 20 20 20 20 20 31 30 30 38 20 2f 2a 20 69         1008 /* i
1a180 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
1a190 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
1a1a0 49 47 5f 4d 41 58 20 20 20 20 20 20 20 20 20 20  IG_MAX          
1a1b0 20 20 20 20 20 20 20 20 20 31 30 30 38 20 2f 2a           1008 /*
1a1c0 20 4c 61 72 67 65 73 74 20 44 42 43 4f 4e 46 49   Largest DBCONFI
1a1d0 47 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  G */../*.** CAPI
1a1e0 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
1a1f0 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64  Disable Extended
1a200 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
1a210 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1a220 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1a230 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
1a240 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
1a250 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
1a260 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
1a270 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
1a280 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
1a290 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65  f SQLite. ^The e
1a2a0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a  xtended result.*
1a2b0 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61  * codes are disa
1a2c0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
1a2d0 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63  for historical c
1a2e0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f  ompatibility..*/
1a2f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
1a300 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
1a310 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
1a320 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
1a330 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
1a340 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d  nsert Rowid.** M
1a350 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1a360 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79  *.** ^Each entry
1a370 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20   in most SQLite 
1a380 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66  tables (except f
1a390 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49  or [WITHOUT ROWI
1a3a0 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61  D] tables).** ha
1a3b0 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
1a3c0 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
1a3d0 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
1a3e0 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77  he [ROWID | "row
1a3f0 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64  id"]. ^The rowid
1a400 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c   is always avail
1a410 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e  able.** as an un
1a420 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20  declared column 
1a430 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44  named ROWID, OID
1a440 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20  , or _ROWID_ as 
1a450 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a  long as those.**
1a460 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61   names are not a
1a470 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c  lso used by expl
1a480 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
1a490 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20  columns. ^If.** 
1a4a0 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  the table has a 
1a4b0 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b  column of type [
1a4c0 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
1a4d0 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63  KEY] then that c
1a4e0 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74  olumn.** is anot
1a4f0 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68  her alias for th
1a500 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e  e rowid..**.** ^
1a510 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  The sqlite3_last
1a520 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
1a530 20 69 6e 74 65 72 66 61 63 65 20 75 73 75 61 6c   interface usual
1a540 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ly returns the [
1a550 72 6f 77 69 64 5d 20 6f 66 0a 2a 2a 20 74 68 65  rowid] of.** the
1a560 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63   most recent suc
1a570 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
1a580 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61   into a rowid ta
1a590 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20  ble or [virtual 
1a5a0 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74  table].** on dat
1a5b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a5c0 20 44 2e 20 5e 49 6e 73 65 72 74 73 20 69 6e 74   D. ^Inserts int
1a5d0 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44  o [WITHOUT ROWID
1a5e0 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74  ] tables are not
1a5f0 0a 2a 2a 20 72 65 63 6f 72 64 65 64 2e 20 5e 49  .** recorded. ^I
1a600 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20  f no successful 
1a610 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72  [INSERT]s into r
1a620 6f 77 69 64 20 74 61 62 6c 65 73 20 68 61 76 65  owid tables have
1a630 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 0a   ever occurred .
1a640 2a 2a 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ** on the databa
1a650 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c  se connection D,
1a660 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61   then sqlite3_la
1a670 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1a680 44 29 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 7a  D) returns .** z
1a690 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 65  ero..**.** As we
1a6a0 6c 6c 20 61 73 20 62 65 69 6e 67 20 73 65 74 20  ll as being set 
1a6b0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 73  automatically as
1a6c0 20 72 6f 77 73 20 61 72 65 20 69 6e 73 65 72 74   rows are insert
1a6d0 65 64 20 69 6e 74 6f 20 64 61 74 61 62 61 73 65  ed into database
1a6e0 0a 2a 2a 20 74 61 62 6c 65 73 2c 20 74 68 65 20  .** tables, the 
1a6f0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1a700 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  y this function 
1a710 6d 61 79 20 62 65 20 73 65 74 20 65 78 70 6c 69  may be set expli
1a720 63 69 74 6c 79 20 62 79 0a 2a 2a 20 5b 73 71 6c  citly by.** [sql
1a730 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
1a740 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
1a750 0a 2a 2a 20 53 6f 6d 65 20 76 69 72 74 75 61 6c  .** Some virtual
1a760 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
1a770 61 74 69 6f 6e 73 20 6d 61 79 20 49 4e 53 45 52  ations may INSER
1a780 54 20 72 6f 77 73 20 69 6e 74 6f 20 72 6f 77 69  T rows into rowi
1a790 64 20 74 61 62 6c 65 73 20 61 73 0a 2a 2a 20 70  d tables as.** p
1a7a0 61 72 74 20 6f 66 20 63 6f 6d 6d 69 74 74 69 6e  art of committin
1a7b0 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  g a transaction 
1a7c0 28 65 2e 67 2e 20 74 6f 20 66 6c 75 73 68 20 64  (e.g. to flush d
1a7d0 61 74 61 20 61 63 63 75 6d 75 6c 61 74 65 64 20  ata accumulated 
1a7e0 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 74 6f 20  in memory.** to 
1a7f0 64 69 73 6b 29 2e 20 49 6e 20 74 68 69 73 20 63  disk). In this c
1a800 61 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 63  ase subsequent c
1a810 61 6c 6c 73 20 74 6f 20 74 68 69 73 20 66 75 6e  alls to this fun
1a820 63 74 69 6f 6e 20 72 65 74 75 72 6e 20 74 68 65  ction return the
1a830 20 72 6f 77 69 64 0a 2a 2a 20 61 73 73 6f 63 69   rowid.** associ
1a840 61 74 65 64 20 77 69 74 68 20 74 68 65 73 65 20  ated with these 
1a850 69 6e 74 65 72 6e 61 6c 20 49 4e 53 45 52 54 20  internal INSERT 
1a860 6f 70 65 72 61 74 69 6f 6e 73 2c 20 77 68 69 63  operations, whic
1a870 68 20 6c 65 61 64 73 20 74 6f 20 0a 2a 2a 20 75  h leads to .** u
1a880 6e 69 6e 74 75 69 74 69 76 65 20 72 65 73 75 6c  nintuitive resul
1a890 74 73 2e 20 56 69 72 74 75 61 6c 20 74 61 62 6c  ts. Virtual tabl
1a8a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1a8b0 73 20 74 68 61 74 20 64 6f 20 77 72 69 74 65 20  s that do write 
1a8c0 74 6f 20 72 6f 77 69 64 0a 2a 2a 20 74 61 62 6c  to rowid.** tabl
1a8d0 65 73 20 69 6e 20 74 68 69 73 20 77 61 79 20 63  es in this way c
1a8e0 61 6e 20 61 76 6f 69 64 20 74 68 69 73 20 70 72  an avoid this pr
1a8f0 6f 62 6c 65 6d 20 62 79 20 72 65 73 74 6f 72 69  oblem by restori
1a900 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ng the original 
1a910 0a 2a 2a 20 72 6f 77 69 64 20 76 61 6c 75 65 20  .** rowid value 
1a920 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
1a930 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  et_last_insert_r
1a940 6f 77 69 64 28 29 5d 20 62 65 66 6f 72 65 20 72  owid()] before r
1a950 65 74 75 72 6e 69 6e 67 20 0a 2a 2a 20 63 6f 6e  eturning .** con
1a960 74 72 6f 6c 20 74 6f 20 74 68 65 20 75 73 65 72  trol to the user
1a970 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20  ..**.** ^(If an 
1a980 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20  [INSERT] occurs 
1a990 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
1a9a0 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
1a9b0 6e 65 20 77 69 6c 6c 20 0a 2a 2a 20 72 65 74 75  ne will .** retu
1a9c0 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  rn the [rowid] o
1a9d0 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 20 72  f the inserted r
1a9e0 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ow as long as th
1a9f0 65 20 74 72 69 67 67 65 72 20 69 73 20 0a 2a 2a  e trigger is .**
1aa00 20 72 75 6e 6e 69 6e 67 2e 20 4f 6e 63 65 20 74   running. Once t
1aa10 68 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  he trigger progr
1aa20 61 6d 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c  am ends, the val
1aa30 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20  ue returned .** 
1aa40 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
1aa50 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20  reverts to what 
1aa60 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68  it was before th
1aa70 65 20 74 72 69 67 67 65 72 20 77 61 73 20 66 69  e trigger was fi
1aa80 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  red.)^.**.** ^An
1aa90 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66   [INSERT] that f
1aaa0 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
1aab0 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
1aac0 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
1aad0 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
1aae0 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  T] and does not 
1aaf0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
1ab00 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
1ab10 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e  s.** routine.  ^
1ab20 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46  Thus INSERT OR F
1ab30 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49  AIL, INSERT OR I
1ab40 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52  GNORE, INSERT OR
1ab50 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e   ROLLBACK,.** an
1ab60 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52  d INSERT OR ABOR
1ab70 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65  T make no change
1ab80 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20  s to the return 
1ab90 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a  value of this.**
1aba0 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68   routine when th
1abb0 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61  eir insertion fa
1abc0 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53  ils.  ^(When INS
1abd0 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a  ERT OR REPLACE.*
1abe0 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63  * encounters a c
1abf0 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
1ac00 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74  ion, it does not
1ac10 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49   fail.  The.** I
1ac20 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20  NSERT continues 
1ac30 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66  to completion af
1ac40 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77  ter deleting row
1ac50 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a  s that caused.**
1ac60 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
1ac70 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52  problem so INSER
1ac80 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c  T OR REPLACE wil
1ac90 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a  l always change.
1aca0 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ** the return va
1acb0 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  lue of this inte
1acc0 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rface.)^.**.** ^
1acd0 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
1ace0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
1acf0 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73  , an [INSERT] is
1ad00 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a   considered to.*
1ad10 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20  * be successful 
1ad20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75  even if it is su
1ad30 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65  bsequently rolle
1ad40 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
1ad50 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
1ad60 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c  ccessible to SQL
1ad70 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20   statements via 
1ad80 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73  the.** [last_ins
1ad90 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20  ert_rowid() SQL 
1ada0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
1adb0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
1adc0 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61  hread performs a
1add0 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e   new [INSERT] on
1ade0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74   the same.** dat
1adf0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ae00 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69   while the [sqli
1ae10 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1ae20 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63  rowid()].** func
1ae30 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20  tion is running 
1ae40 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73  and thus changes
1ae50 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
1ae60 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65   [rowid],.** the
1ae70 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
1ae80 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1ae90 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1aea0 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72  id()] is.** unpr
1aeb0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69  edictable and mi
1aec0 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69  ght not equal ei
1aed0 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20  ther the old or 
1aee0 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20  the new.** last 
1aef0 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a  insert [rowid]..
1af00 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
1af10 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
1af20 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
1af30 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1af40 49 33 52 45 46 3a 20 53 65 74 20 74 68 65 20 4c  I3REF: Set the L
1af50 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
1af60 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d 45 54 48 4f   value..** METHO
1af70 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1af80 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   The sqlite3_set
1af90 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1afa0 69 64 28 44 2c 20 52 29 20 6d 65 74 68 6f 64 20  id(D, R) method 
1afb0 61 6c 6c 6f 77 73 20 74 68 65 20 61 70 70 6c 69  allows the appli
1afc0 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 73 65 74  cation to.** set
1afd0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1afe0 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 73  ned by calling s
1aff0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
1b000 72 74 5f 72 6f 77 69 64 28 44 29 20 74 6f 20 52  rt_rowid(D) to R
1b010 20 0a 2a 2a 20 77 69 74 68 6f 75 74 20 69 6e 73   .** without ins
1b020 65 72 74 69 6e 67 20 61 20 72 6f 77 20 69 6e 74  erting a row int
1b030 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a  o the database..
1b040 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
1b050 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  set_last_insert_
1b060 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 2c 73  rowid(sqlite3*,s
1b070 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a  qlite3_int64);..
1b080 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b090 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72  Count The Number
1b0a0 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
1b0b0 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
1b0c0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1b0d0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1b0e0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1b0f0 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 69  rows modified, i
1b100 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65  nserted or.** de
1b110 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73  leted by the mos
1b120 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
1b130 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44  eted INSERT, UPD
1b140 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  ATE or DELETE.**
1b150 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68   statement on th
1b160 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1b170 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20  ction specified 
1b180 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  by the only para
1b190 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75  meter..** ^Execu
1b1a0 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74  ting any other t
1b1b0 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ype of SQL state
1b1c0 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f  ment does not mo
1b1d0 64 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a 2a  dify the value.*
1b1e0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  * returned by th
1b1f0 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  is function..**.
1b200 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73  ** ^Only changes
1b210 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20 62   made directly b
1b220 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50  y the INSERT, UP
1b230 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
1b240 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20  tatement are.** 
1b250 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75 78  considered - aux
1b260 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63  iliary changes c
1b270 61 75 73 65 64 20 62 79 20 5b 43 52 45 41 54 45  aused by [CREATE
1b280 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
1b290 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69  ers], .** [forei
1b2a0 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20  gn key actions] 
1b2b0 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  or [REPLACE] con
1b2c0 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
1b2d0 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  on are not count
1b2e0 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67  ed..** .** Chang
1b2f0 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61  es to a view tha
1b300 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65  t are intercepte
1b310 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41  d by .** [INSTEA
1b320 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20 49  D OF trigger | I
1b330 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
1b340 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  rs] are not coun
1b350 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 20  ted. ^The value 
1b360 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
1b370 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1b380 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66  ) immediately af
1b390 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 55  ter an INSERT, U
1b3a0 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c  PDATE or .** DEL
1b3b0 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72 75  ETE statement ru
1b3c0 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20 61  n on a view is a
1b3d0 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79  lways zero. Only
1b3e0 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74 6f   changes made to
1b3f0 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73   real .** tables
1b400 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   are counted..**
1b410 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20 6d  .** Things are m
1b420 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20  ore complicated 
1b430 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  if the sqlite3_c
1b440 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
1b450 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 64  n is.** executed
1b460 20 77 68 69 6c 65 20 61 20 74 72 69 67 67 65 72   while a trigger
1b470 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e   program is runn
1b480 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68 61  ing. This may ha
1b490 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70  ppen if the.** p
1b4a0 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65 20  rogram uses the 
1b4b0 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
1b4c0 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20  unction], or if 
1b4d0 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c 62  some other callb
1b4e0 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
1b4f0 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f  invokes sqlite3_
1b500 63 68 61 6e 67 65 73 28 29 20 64 69 72 65 63 74  changes() direct
1b510 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a  ly. Essentially:
1b520 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  .** .** <ul>.** 
1b530 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20    <li> ^(Before 
1b540 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67 67  entering a trigg
1b550 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20 76  er program the v
1b560 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1b570 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69 74  .**        sqlit
1b580 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  e3_changes() fun
1b590 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e 20  ction is saved. 
1b5a0 41 66 74 65 72 20 74 68 65 20 74 72 69 67 67 65  After the trigge
1b5b0 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20  r program .**   
1b5c0 20 20 20 20 20 68 61 73 20 66 69 6e 69 73 68 65       has finishe
1b5d0 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  d, the original 
1b5e0 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72 65  value is restore
1b5f0 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c  d.)^.** .**   <l
1b600 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74 72  i> ^(Within a tr
1b610 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 61  igger program ea
1b620 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ch INSERT, UPDAT
1b630 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a  E and DELETE .**
1b640 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e          statemen
1b650 74 20 73 65 74 73 20 74 68 65 20 76 61 6c 75 65  t sets the value
1b660 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1b670 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a  ite3_changes() .
1b680 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20 63  **        upon c
1b690 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72  ompletion as nor
1b6a0 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20  mal. Of course, 
1b6b0 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c 20  this value will 
1b6c0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20  not include .** 
1b6d0 20 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e 67         any chang
1b6e0 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  es performed by 
1b6f0 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61 73  sub-triggers, as
1b700 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
1b710 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20  nges() .**      
1b720 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20    value will be 
1b730 73 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f 72  saved and restor
1b740 65 64 20 61 66 74 65 72 20 65 61 63 68 20 73 75  ed after each su
1b750 62 2d 74 72 69 67 67 65 72 20 68 61 73 20 72 75  b-trigger has ru
1b760 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  n.)^.** </ul>.**
1b770 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73   .** ^This means
1b780 20 74 68 61 74 20 69 66 20 74 68 65 20 63 68 61   that if the cha
1b790 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
1b7a0 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 29  ion (or similar)
1b7b0 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74   is used.** by t
1b7c0 68 65 20 66 69 72 73 74 20 49 4e 53 45 52 54 2c  he first INSERT,
1b7d0 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
1b7e0 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
1b7f0 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69 74  in a trigger, it
1b800 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65   .** returns the
1b810 20 76 61 6c 75 65 20 61 73 20 73 65 74 20 77 68   value as set wh
1b820 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 73  en the calling s
1b830 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 65  tatement began e
1b840 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66  xecuting..** ^If
1b850 20 69 74 20 69 73 20 75 73 65 64 20 62 79 20 74   it is used by t
1b860 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62  he second or sub
1b870 73 65 71 75 65 6e 74 20 73 75 63 68 20 73 74 61  sequent such sta
1b880 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
1b890 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67  trigger .** prog
1b8a0 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 72  ram, the value r
1b8b0 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74 73  eturned reflects
1b8c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
1b8d0 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20  ows modified by 
1b8e0 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73  the .** previous
1b8f0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1b900 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
1b910 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73  ent within the s
1b920 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a  ame trigger..**.
1b930 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
1b940 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
1b950 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
1b960 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
1b970 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
1b980 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61  a], and the [cha
1b990 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
1b9a0 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
1b9b0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
1b9c0 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
1b9d0 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
1b9e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1b9f0 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
1ba00 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
1ba10 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
1ba20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
1ba30 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  * is unpredictab
1ba40 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
1ba50 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
1ba60 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71  lite3_changes(sq
1ba70 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1ba80 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20  CAPI3REF: Total 
1ba90 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
1baa0 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f  odified.** METHO
1bab0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1bac0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
1bad0 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61  returns the tota
1bae0 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  l number of rows
1baf0 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 66   inserted, modif
1bb00 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65  ied or.** delete
1bb10 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54  d by all [INSERT
1bb20 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b  ], [UPDATE] or [
1bb30 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
1bb40 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20  ts completed.** 
1bb50 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61  since the databa
1bb60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61  se connection wa
1bb70 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64  s opened, includ
1bb80 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75 74  ing those execut
1bb90 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66  ed as.** part of
1bba0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1bbb0 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e  s. ^Executing an
1bbc0 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20  y other type of 
1bbd0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
1bbe0 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 74   does not affect
1bbf0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1bc00 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  ned by sqlite3_t
1bc10 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a  otal_changes()..
1bc20 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20  ** .** ^Changes 
1bc30 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20  made as part of 
1bc40 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
1bc50 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 64  ions] are includ
1bc60 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75  ed in the.** cou
1bc70 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d 61  nt, but those ma
1bc80 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 52 45  de as part of RE
1bc90 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74  PLACE constraint
1bca0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a   resolution are.
1bcb0 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73  ** not. ^Changes
1bcc0 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
1bcd0 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20  are intercepted 
1bce0 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72  by INSTEAD OF tr
1bcf0 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e  iggers .** are n
1bd00 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a  ot counted..** .
1bd10 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
1bd20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
1bd30 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
1bd40 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
1bd50 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
1bd60 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61  d the [total_cha
1bd70 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
1bd80 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
1bd90 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
1bda0 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
1bdb0 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
1bdc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1bdd0 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
1bde0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
1bdf0 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
1be00 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72  n the value.** r
1be10 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65  eturned is unpre
1be20 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
1be30 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
1be40 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  int sqlite3_tota
1be50 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  l_changes(sqlite
1be60 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
1be70 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20  3REF: Interrupt 
1be80 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51  A Long-Running Q
1be90 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  uery.** METHOD: 
1bea0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1beb0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
1bec0 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
1bed0 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
1bee0 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
1bef0 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
1bf00 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
1bf10 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
1bf20 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
1bf30 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
1bf40 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
1bf50 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
1bf60 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
1bf70 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
1bf80 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
1bf90 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
1bfa0 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
1bfb0 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
1bfc0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
1bfd0 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
1bfe0 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
1bff0 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
1c000 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
1c010 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
1c020 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
1c030 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
1c040 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
1c050 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
1c060 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
1c070 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
1c080 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1c090 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
1c0a0 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
1c0b0 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
1c0c0 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
1c0d0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
1c0e0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
1c0f0 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
1c100 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
1c110 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
1c120 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1c130 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
1c140 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
1c150 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
1c160 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
1c170 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
1c180 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
1c190 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
1c1a0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
1c1b0 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
1c1c0 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
1c1d0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
1c1e0 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
1c1f0 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
1c200 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
1c210 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
1c220 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
1c230 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
1c240 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
1c250 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
1c260 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
1c270 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
1c280 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
1c290 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
1c2a0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1c2b0 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
1c2c0 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
1c2d0 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
1c2e0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
1c2f0 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
1c300 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1c310 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
1c320 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
1c330 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
1c340 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
1c350 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1c360 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
1c370 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
1c380 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
1c390 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
1c3a0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
1c3b0 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
1c3c0 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
1c3d0 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
1c3e0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
1c3f0 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
1c400 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1c410 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1c420 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
1c430 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
1c440 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
1c450 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
1c460 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
1c470 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
1c480 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
1c490 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
1c4a0 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
1c4b0 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
1c4c0 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
1c4d0 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
1c4e0 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
1c4f0 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
1c500 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
1c510 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
1c520 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1c530 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
1c540 75 72 6e 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  urns..*/.void sq
1c550 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1c560 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1c570 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
1c580 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
1c590 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d  Statement Is Com
1c5a0 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73  plete.**.** Thes
1c5b0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
1c5c0 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d  seful during com
1c5d0 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
1c5e0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
1c5f0 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
1c600 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
1c610 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f  ems to form a co
1c620 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
1c630 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
1c640 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
1c650 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
1c660 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
1c670 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
1c680 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54  for parsing.  ^T
1c690 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1c6a0 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e  turn 1 if the in
1c6b0 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70  put string.** ap
1c6c0 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f  pears to be a co
1c6d0 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
1c6e0 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d  ment.  ^A statem
1c6f0 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f  ent is judged to
1c700 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20   be.** complete 
1c710 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20  if it ends with 
1c720 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65  a semicolon toke
1c730 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  n and is not a p
1c740 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65  refix of a.** we
1c750 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45  ll-formed CREATE
1c760 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
1c770 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73  nt.  ^Semicolons
1c780 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64   that are embedd
1c790 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72  ed within.** str
1c7a0 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20  ing literals or 
1c7b0 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65  quoted identifie
1c7c0 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65  r names or comme
1c7d0 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69  nts are not.** i
1c7e0 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e  ndependent token
1c7f0 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74  s (they are part
1c800 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e   of the token in
1c810 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a   which they are.
1c820 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64  ** embedded) and
1c830 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75   thus do not cou
1c840 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e  nt as a statemen
1c850 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  t terminator.  ^
1c860 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e  Whitespace.** an
1c870 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20  d comments that 
1c880 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c  follow the final
1c890 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69   semicolon are i
1c8a0 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gnored..**.** ^T
1c8b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1c8c0 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74  turn 0 if the st
1c8d0 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d  atement is incom
1c8e0 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a  plete.  ^If a.**
1c8f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1c900 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53  on fails, then S
1c910 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72  QLITE_NOMEM is r
1c920 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
1c930 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64  These routines d
1c940 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20  o not parse the 
1c950 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74  SQL statements t
1c960 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  hus.** will not 
1c970 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63  detect syntactic
1c980 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53  ally incorrect S
1c990 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53  QL..**.** ^(If S
1c9a0 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65  QLite has not be
1c9b0 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75  en initialized u
1c9c0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e  sing [sqlite3_in
1c9d0 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f  itialize()] prio
1c9e0 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e  r .** to invokin
1c9f0 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  g sqlite3_comple
1ca00 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69  te16() then sqli
1ca10 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
1ca20 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
1ca30 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
1ca40 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1ca50 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69  16().  If that i
1ca60 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61  nitialization fa
1ca70 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ils,.** then the
1ca80 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
1ca90 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  om sqlite3_compl
1caa0 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20  ete16() will be 
1cab0 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61  non-zero.** rega
1cac0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
1cad0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70  r or not the inp
1cae0 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65  ut SQL is comple
1caf0 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te.)^.**.** The 
1cb00 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1cb10 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75  3_complete()] mu
1cb20 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
1cb30 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38  minated.** UTF-8
1cb40 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
1cb50 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
1cb60 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1cb70 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
1cb80 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1cb90 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
1cba0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1cbb0 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
1cbc0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
1cbd0 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e  t char *sql);.in
1cbe0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
1cbf0 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
1cc00 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
1cc10 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
1cc20 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
1cc30 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
1cc40 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57  Y Errors.** KEYW
1cc50 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64  ORDS: {busy-hand
1cc60 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62  ler callback} {b
1cc70 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20  usy handler}.** 
1cc80 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1cc90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1cca0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1ccb0 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73  D,X,P) routine s
1ccc0 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ets a callback f
1ccd0 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61  unction X.** tha
1cce0 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
1ccf0 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ed with argument
1cd00 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61   P whenever.** a
1cd10 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
1cd20 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61  e to access a da
1cd30 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73  tabase table ass
1cd40 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20  ociated with.** 
1cd50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1cd60 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f  tion] D when ano
1cd70 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f  ther thread.** o
1cd80 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68  r process has th
1cd90 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a  e table locked..
1cda0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
1cdb0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e  usy_handler() in
1cdc0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
1cdd0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20  to implement.** 
1cde0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
1cdf0 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52  meout()] and [PR
1ce00 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
1ce10 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  t]..**.** ^If th
1ce20 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
1ce30 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
1ce40 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69  QLITE_BUSY].** i
1ce50 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
1ce60 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
1ce70 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
1ce80 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79  k.  ^If the busy
1ce90 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
1cea0 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
1ceb0 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68  he callback migh
1cec0 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
1ced0 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
1cee0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
1cef0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
1cf00 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
1cf10 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
1cf20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
1cf30 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
1cf40 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
1cf50 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1cf60 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65  dler().  ^The se
1cf70 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
1cf80 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
1cf90 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
1cfa0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
1cfb0 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
1cfc0 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
1cfd0 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70  * been invoked p
1cfe0 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68  reviously for th
1cff0 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65  e same locking e
1d000 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
1d010 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
1d020 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
1d030 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
1d040 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
1d050 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
1d060 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
1d070 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72  QLITE_BUSY] is r
1d080 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68  eturned.** to th
1d090 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a  e application..*
1d0a0 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
1d0b0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
1d0c0 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
1d0d0 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
1d0e0 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74  made to access t
1d0f0 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
1d100 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74  the cycle repeat
1d110 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  s..**.** The pre
1d120 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20  sence of a busy 
1d130 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74  handler does not
1d140 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
1d150 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  it will be invok
1d160 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65  ed.** when there
1d170 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74   is lock content
1d180 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ion. ^If SQLite 
1d190 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20  determines that 
1d1a0 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
1d1b0 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75  y.** handler cou
1d1c0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64  ld result in a d
1d1d0 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c  eadlock, it will
1d1e0 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65   go ahead and re
1d1f0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
1d200 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  Y].** to the app
1d210 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64  lication instead
1d220 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65   of invoking the
1d230 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65   .** busy handle
1d240 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
1d250 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
1d260 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
1d270 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
1d280 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
1d290 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
1d2a0 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
1d2b0 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
1d2c0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
1d2d0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
1d2e0 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
1d2f0 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
1d300 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
1d310 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
1d320 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
1d330 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
1d340 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
1d350 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
1d360 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
1d370 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
1d380 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
1d390 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
1d3a0 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
1d3b0 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
1d3c0 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
1d3d0 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
1d3e0 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
1d3f0 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
1d400 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
1d410 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
1d420 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
1d430 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
1d440 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
1d450 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
1d460 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
1d470 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
1d480 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
1d490 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
1d4a0 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
1d4b0 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
1d4c0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
1d4d0 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
1d4e0 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  is NULL..**.** ^
1d4f0 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
1d500 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
1d510 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
1d520 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
1d530 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d540 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
1d550 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
1d560 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
1d570 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
1d580 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74  dler.)^  ^Note t
1d590 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
1d5a0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1d5b0 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75  t()].** or evalu
1d5c0 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75  ating [PRAGMA bu
1d5d0 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69  sy_timeout=N] wi
1d5e0 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  ll change the.**
1d5f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e   busy handler an
1d600 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79  d thus clear any
1d610 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
1d620 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
1d630 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
1d640 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
1d650 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
1d660 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
1d670 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
1d680 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
1d690 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
1d6a0 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68  handler.  In oth
1d6b0 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65  er words,.** the
1d6c0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1d6d0 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20   not reentrant. 
1d6e0 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
1d6f0 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
1d700 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
1d710 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79  r..** .** A busy
1d720 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
1d730 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
1d740 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1d750 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20  ** or [prepared 
1d760 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
1d770 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
1d780 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74   handler..*/.int
1d790 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1d7a0 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 69  ndler(sqlite3*,i
1d7b0 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29  nt(*)(void*,int)
1d7c0 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ,void*);../*.** 
1d7d0 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20  CAPI3REF: Set A 
1d7e0 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20  Busy Timeout.** 
1d7f0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1d800 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1d810 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
1d820 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1d830 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
1d840 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
1d850 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
1d860 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
1d870 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
1d880 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e  ocked.  ^The han
1d890 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
1d8a0 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
1d8b0 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
1d8c0 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
1d8d0 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
1d8e0 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
1d8f0 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c  ed.  ^After at l
1d900 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
1d910 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
1d920 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
1d930 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
1d940 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
1d950 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
1d960 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
1d970 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  BUSY]..**.** ^Ca
1d980 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
1d990 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
1d9a0 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
1d9b0 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
1d9c0 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
1d9d0 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
1d9e0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1d9f0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1da00 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
1da10 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
1da20 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1da30 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20  nection] at any 
1da40 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
1da50 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
1da60 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
1da70 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
1da80 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1da90 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
1daa0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
1dab0 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
1dac0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
1dad0 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a  r is cleared.)^.
1dae0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
1daf0 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1db00 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71  meout].*/.int sq
1db10 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1db20 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ut(sqlite3*, int
1db30 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   ms);../*.** CAP
1db40 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e  I3REF: Convenien
1db50 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20  ce Routines For 
1db60 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a  Running Queries.
1db70 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1db80 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e3.**.** This is
1db90 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66   a legacy interf
1dba0 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73  ace that is pres
1dbb0 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61  erved for backwa
1dbc0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1dbd0 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69  y..** Use of thi
1dbe0 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  s interface is n
1dbf0 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  ot recommended..
1dc00 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
1dc10 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
1dc20 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
1dc30 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
1dc40 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
1dc50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
1dc60 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
1dc70 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
1dc80 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
1dc90 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
1dca0 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
1dcb0 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
1dcc0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
1dcd0 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
1dce0 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
1dcf0 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
1dd00 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
1dd10 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
1dd20 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
1dd30 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
1dd40 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
1dd50 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
1dd60 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
1dd70 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
1dd80 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
1dd90 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
1dda0 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
1ddb0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1ddc0 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
1ddd0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
1dde0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1ddf0 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  -8 strings..** T
1de00 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d  here are (N+1)*M
1de10 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65   elements in the
1de20 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72   array.  The fir
1de30 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f  st M pointers po
1de40 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74  int.** to zero-t
1de50 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
1de60 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20  s that  contain 
1de70 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  the names of the
1de80 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65   columns..** The
1de90 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69   remaining entri
1dea0 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20  es all point to 
1deb0 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20  query results.  
1dec0 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75  NULL values resu
1ded0 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f  lt.** in NULL po
1dee0 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68  inters.  All oth
1def0 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  er values are in
1df00 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72   their UTF-8 zer
1df10 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1df20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74  string represent
1df30 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65  ation as returne
1df40 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
1df50 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
1df60 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1df70 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74  le might consist
1df80 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
1df90 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1dfa0 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  ns..** It is not
1dfb0 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20   safe to pass a 
1dfc0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72  result table dir
1dfd0 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65  ectly to [sqlite
1dfe0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20  3_free()]..** A 
1dff0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f  result table sho
1e000 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  uld be deallocat
1e010 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1e020 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
1e030 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65  .**.** ^(As an e
1e040 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65  xample of the re
1e050 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61  sult table forma
1e060 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65  t, suppose a que
1e070 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  ry result.** is 
1e080 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1e090 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1e0a0 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61  re>.**        Na
1e0b0 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a  me        | Age.
1e0c0 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d  **        ------
1e0d0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1e0e0 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63  -.**        Alic
1e0f0 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20  e       | 43.** 
1e100 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20         Bob      
1e110 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20     | 28.**      
1e120 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20    Cindy       | 
1e130 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  21.** </pre></bl
1e140 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1e150 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f  There are two co
1e160 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20  lumn (M==2) and 
1e170 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33  three rows (N==3
1e180 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20  ).  Thus the.** 
1e190 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73  result table has
1e1a0 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70   8 entries.  Sup
1e1b0 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20  pose the result 
1e1c0 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a  table is stored.
1e1d0 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e  ** in an array n
1e1e0 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20  ames azResult.  
1e1f0 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f  Then azResult ho
1e200 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74  lds this content
1e210 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1e220 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
1e230 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1e240 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a  ;0] = "Name";.**
1e250 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1e260 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b  &#91;1] = "Age";
1e270 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1e280 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c  ult&#91;2] = "Al
1e290 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ice";.**        
1e2a0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20  azResult&#91;3] 
1e2b0 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20  = "43";.**      
1e2c0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34    azResult&#91;4
1e2d0 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20  ] = "Bob";.**   
1e2e0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1e2f0 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20  1;5] = "28";.** 
1e300 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1e310 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22  #91;6] = "Cindy"
1e320 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1e330 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32  sult&#91;7] = "2
1e340 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  1";.** </pre></b
1e350 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
1e360 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1e370 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63  get_table() func
1e380 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f  tion evaluates o
1e390 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65  ne or more.** se
1e3a0 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
1e3b0 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
1e3c0 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   in the zero-ter
1e3d0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
1e3e0 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32   string of its 2
1e3f0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
1e400 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
1e410 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a  t table to the.*
1e420 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20  * pointer given 
1e430 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  in its 3rd param
1e440 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  eter..**.** Afte
1e450 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
1e460 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  n has finished w
1e470 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66  ith the result f
1e480 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  rom sqlite3_get_
1e490 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d  table(),.** it m
1e4a0 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73  ust pass the res
1e4b0 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65  ult table pointe
1e4c0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  r to sqlite3_fre
1e4d0 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64  e_table() in ord
1e4e0 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65  er to.** release
1e4f0 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74   the memory that
1e500 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20   was malloced.  
1e510 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77  Because of the w
1e520 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ay the.** [sqlit
1e530 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70  e3_malloc()] hap
1e540 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69  pens within sqli
1e550 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
1e560 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20   the calling.** 
1e570 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  function must no
1e580 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73  t try to call [s
1e590 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64  qlite3_free()] d
1e5a0 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a  irectly.  Only.*
1e5b0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  * [sqlite3_free_
1e5c0 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65  table()] is able
1e5d0 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20   to release the 
1e5e0 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20  memory properly 
1e5f0 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a  and safely..**.*
1e600 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
1e610 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66  t_table() interf
1e620 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ace is implement
1e630 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20  ed as a wrapper 
1e640 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
1e650 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65  e3_exec()].  The
1e660 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1e670 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  le() routine doe
1e680 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73  s not have acces
1e690 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65  s.** to any inte
1e6a0 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74  rnal data struct
1e6b0 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ures of SQLite. 
1e6c0 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68   It uses only th
1e6d0 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65  e public.** inte
1e6e0 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65  rface defined he
1e6f0 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71  re.  As a conseq
1e700 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68  uence, errors th
1e710 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a  at occur in the.
1e720 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72  ** wrapper layer
1e730 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
1e740 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65  internal [sqlite
1e750 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61  3_exec()] call a
1e760 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63  re not.** reflec
1e770 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e  ted in subsequen
1e780 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
1e790 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f  te3_errcode()] o
1e7a0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  r.** [sqlite3_er
1e7b0 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  rmsg()]..*/.int 
1e7c0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1e7d0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
1e7e0 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e  ,          /* An
1e7f0 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
1e800 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1e810 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c  zSql,     /* SQL
1e820 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
1e830 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61   */.  char ***pa
1e840 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52  zResult,    /* R
1e850 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
1e860 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ery */.  int *pn
1e870 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Row,           /
1e880 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1e890 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
1e8a0 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  here */.  int *p
1e8b0 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  nColumn,        
1e8c0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1e8d0 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
1e8e0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
1e8f0 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20  ar **pzErrmsg   
1e900 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
1e910 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1e920 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .);.void sqlite3
1e930 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
1e940 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
1e950 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
1e960 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
1e970 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
1e980 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1e990 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61  tines are work-a
1e9a0 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72  likes of the "pr
1e9b0 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f  intf()" family o
1e9c0 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66  f functions.** f
1e9d0 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
1e9e0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54   C library..** T
1e9f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e  hese routines un
1ea00 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66  derstand most of
1ea10 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 66 6f 72 6d   the common form
1ea20 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66  atting options f
1ea30 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
1ea40 61 72 64 20 6c 69 62 72 61 72 79 20 70 72 69 6e  ard library prin
1ea50 74 66 28 29 20 0a 2a 2a 20 70 6c 75 73 20 73 6f  tf() .** plus so
1ea60 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f  me additional no
1ea70 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61  n-standard forma
1ea80 74 73 20 28 5b 25 71 5d 2c 20 5b 25 51 5d 2c 20  ts ([%q], [%Q], 
1ea90 5b 25 77 5d 2c 20 61 6e 64 20 5b 25 7a 5d 29 2e  [%w], and [%z]).
1eaa0 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 62 75 69  .** See the [bui
1eab0 6c 74 2d 69 6e 20 70 72 69 6e 74 66 28 29 5d 20  lt-in printf()] 
1eac0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
1ead0 72 20 64 65 74 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  r details..**.**
1eae0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70   ^The sqlite3_mp
1eaf0 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69  rintf() and sqli
1eb00 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72  te3_vmprintf() r
1eb10 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68  outines write th
1eb20 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  eir.** results i
1eb30 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
1eb40 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
1eb50 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d 2e 0a 2a  3_malloc64()]..*
1eb60 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
1eb70 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
1eb80 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
1eb90 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
1eba0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
1ebb0 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72  ree()].  ^Both r
1ebc0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
1ebd0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
1ebe0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
1ebf0 6c 6f 63 36 34 28 29 5d 20 69 73 20 75 6e 61 62  loc64()] is unab
1ec00 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
1ec10 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
1ec20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
1ec30 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
1ec40 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1ec50 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
1ec60 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
1ec70 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
1ec80 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
1ec90 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
1eca0 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
1ecb0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
1ecc0 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
1ecd0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1ece0 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
1ecf0 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
1ed00 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
1ed10 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
1ed20 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
1ed30 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
1ed40 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
1ed50 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
1ed60 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
1ed70 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
1ed80 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
1ed90 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
1eda0 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
1edb0 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
1edc0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1edd0 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
1ede0 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
1edf0 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
1ee00 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
1ee10 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
1ee20 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
1ee30 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
1ee40 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
1ee50 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
1ee60 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
1ee70 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
1ee80 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
1ee90 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
1eea0 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
1eeb0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
1eec0 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
1eed0 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
1eee0 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
1eef0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
1ef00 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
1ef10 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
1ef20 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
1ef30 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
1ef40 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
1ef50 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
1ef60 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1ef70 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
1ef80 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
1ef90 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
1efa0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
1efb0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
1efc0 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
1efd0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
1efe0 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
1eff0 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
1f000 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1f010 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
1f020 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
1f030 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
1f040 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
1f050 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
1f060 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1f070 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
1f080 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
1f090 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
1f0a0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1f0b0 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  f()..**.** See a
1f0c0 6c 73 6f 3a 20 20 5b 62 75 69 6c 74 2d 69 6e 20  lso:  [built-in 
1f0d0 70 72 69 6e 74 66 28 29 5d 2c 20 5b 70 72 69 6e  printf()], [prin
1f0e0 74 66 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  tf() SQL functio
1f0f0 6e 5d 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69  n].*/.char *sqli
1f100 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
1f110 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68  t char*,...);.ch
1f120 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
1f130 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1f140 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72  , va_list);.char
1f150 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   *sqlite3_snprin
1f160 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1f170 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
1f180 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73  char *sqlite3_vs
1f190 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1f1a0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  *,const char*, v
1f1b0 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  a_list);../*.** 
1f1c0 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1f1d0 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
1f1e0 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
1f1f0 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
1f200 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
1f210 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
1f220 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
1f230 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
1f240 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
1f250 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
1f260 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
1f270 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
1f280 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
1f290 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
1f2a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
1f2b0 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
1f2c0 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
1f2d0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1f2e0 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
1f2f0 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
1f300 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
1f310 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
1f320 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1f330 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
1f340 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
1f350 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
1f360 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
1f370 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
1f380 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
1f390 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
1f3a0 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
1f3b0 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
1f3c0 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
1f3d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1f3e0 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
1f3f0 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
1f400 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
1f410 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
1f420 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
1f430 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
1f440 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1f450 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1f460 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72  e3_malloc64(N) r
1f470 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73  outine works jus
1f480 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  t like.** sqlite
1f490 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65  3_malloc(N) exce
1f4a0 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20  pt that N is an 
1f4b0 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20  unsigned 64-bit 
1f4c0 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a  integer instead.
1f4d0 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33  ** of a signed 3
1f4e0 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a  2-bit integer..*
1f4f0 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  *.** ^Calling sq
1f500 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
1f510 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
1f520 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
1f530 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
1f540 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
1f550 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
1f560 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
1f570 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
1f580 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
1f590 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72   ^The sqlite3_fr
1f5a0 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
1f5b0 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
1f5c0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
1f5d0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
1f5e0 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
1f5f0 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
1f600 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
1f610 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
1f620 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
1f630 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
1f640 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
1f650 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
1f660 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
1f670 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
1f680 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
1f690 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
1f6a0 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
1f6b0 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
1f6c0 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
1f6d0 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
1f6e0 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
1f6f0 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
1f700 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
1f710 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
1f720 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
1f730 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
1f740 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
1f750 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
1f760 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
1f770 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
1f780 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  alloc()..**.** ^
1f790 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
1f7a0 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61  loc(X,N) interfa
1f7b0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
1f7c0 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
1f7d0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1f7e0 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65  on X to be at le
1f7f0 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20  ast N bytes..** 
1f800 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d 65  ^If the X parame
1f810 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1f820 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69  ealloc(X,N).** i
1f830 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1f840 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
1f850 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
1f860 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
1f870 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e  lite3_malloc(N).
1f880 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61  .** ^If the N pa
1f890 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1f8a0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1f8b0 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65  is zero or.** ne
1f8c0 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20  gative then the 
1f8d0 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63  behavior is exac
1f8e0 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20  tly the same as 
1f8f0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1f900 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e  e3_free(X)..** ^
1f910 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f920 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70  X,N) returns a p
1f930 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
1f940 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
1f950 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
1f960 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
1f970 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63  NULL if insuffic
1f980 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61  ient memory is a
1f990 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
1f9a0 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
1f9b0 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
1f9c0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
1f9d0 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
1f9e0 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
1f9f0 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
1fa00 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
1fa10 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
1fa20 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1fa30 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1fa40 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  N) and the prior
1fa50 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
1fa60 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  reed..** ^If sql
1fa70 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1fa80 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61  ) returns NULL a
1fa90 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65  nd N is positive
1faa0 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72  , then the.** pr
1fab0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
1fac0 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
1fad0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1fae0 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69  realloc64(X,N) i
1faf0 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20  nterfaces works 
1fb00 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73  the same as.** s
1fb10 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1fb20 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  ,N) except that 
1fb30 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e  N is a 64-bit un
1fb40 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69  signed integer i
1fb50 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33  nstead.** of a 3
1fb60 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  2-bit signed int
1fb70 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  eger..**.** ^If 
1fb80 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c  X is a memory al
1fb90 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75  location previou
1fba0 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
1fbb0 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
1fbc0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  (),.** sqlite3_m
1fbd0 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74  alloc64(), sqlit
1fbe0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72  e3_realloc(), or
1fbf0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1fc00 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  64(), then.** sq
1fc10 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72  lite3_msize(X) r
1fc20 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20  eturns the size 
1fc30 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61  of that memory a
1fc40 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74  llocation in byt
1fc50 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  es..** ^The valu
1fc60 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
1fc70 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d  lite3_msize(X) m
1fc80 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74  ight be larger t
1fc90 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a  han the number.*
1fca0 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 65  * of bytes reque
1fcb0 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 20  sted when X was 
1fcc0 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20  allocated.  ^If 
1fcd0 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  X is a NULL poin
1fce0 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ter then.** sqli
1fcf0 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
1fd00 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58  urns zero.  If X
1fd10 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74   points to somet
1fd20 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74  hing that is not
1fd30 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  .** the beginnin
1fd40 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  g of memory allo
1fd50 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74  cation, or if it
1fd60 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72   points to a for
1fd70 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d  merly.** valid m
1fd80 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1fd90 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65   that has now be
1fda0 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74  en freed, then t
1fdb0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
1fdc0 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  f sqlite3_msize(
1fdd0 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  X) is undefined 
1fde0 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72  and possibly har
1fdf0 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mful..**.** ^The
1fe00 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
1fe10 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
1fe20 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  oc(), sqlite3_re
1fe30 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
1fe40 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
1fe50 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
1fe60 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c  loc64().** is al
1fe70 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
1fe80 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
1fe90 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20  te boundary, or 
1fea0 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62  to a.** 4 byte b
1feb0 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b  oundary if the [
1fec0 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c  SQLITE_4_BYTE_AL
1fed0 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f  IGNED_MALLOC] co
1fee0 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
1fef0 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
1ff00 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
1ff10 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
1ff20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
1ff30 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
1ff40 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
1ff50 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
1ff60 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
1ff70 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
1ff80 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
1ff90 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
1ffa0 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
1ffb0 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
1ffc0 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
1ffd0 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
1ffe0 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
1fff0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
20000 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e  ors can be used.
20010 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20  .**.** Prior to 
20020 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
20030 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f  .7.10, the Windo
20040 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  ws OS interface 
20050 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20  layer called.** 
20060 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
20070 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
20080 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
20090 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
200a0 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
200b0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
200c0 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
200d0 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
200e0 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
200f0 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
20100 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
20110 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
20120 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
20130 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65  cation errors we
20140 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
20150 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65  .** they were re
20160 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b  ported back as [
20170 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
20180 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   or.** [SQLITE_I
20190 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61  OERR] rather tha
201a0 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
201b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ..**.** The poin
201c0 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ter arguments to
201d0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
201e0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
201f0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73  ealloc()].** mus
20200 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c  t be either NULL
20210 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72   or else pointer
20220 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
20230 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63  a prior.** invoc
20240 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
20250 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
20260 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
20270 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20  )] that have.** 
20280 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c  not yet been rel
20290 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eased..**.** The
202a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
202b0 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72  t not read or wr
202c0 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a  ite any part of.
202d0 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  ** a block of me
202e0 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61  mory after it ha
202f0 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20  s been released 
20300 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
20310 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
20320 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
20330 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
20340 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
20350 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
20360 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75  lloc64(sqlite3_u
20370 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71  int64);.void *sq
20380 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
20390 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
203a0 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
203b0 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  64(void*, sqlite
203c0 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  3_uint64);.void 
203d0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
203e0 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e  d*);.sqlite3_uin
203f0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  t64 sqlite3_msiz
20400 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
20410 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
20420 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
20430 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
20440 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
20450 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
20460 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
20470 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
20480 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
20490 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
204a0 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
204b0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
204c0 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
204d0 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
204e0 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
204f0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
20500 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
20510 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
20520 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
20530 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
20540 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
20550 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
20560 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
20570 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
20580 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
20590 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
205a0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
205b0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
205c0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
205d0 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
205e0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
205f0 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
20600 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
20610 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
20620 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
20630 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
20640 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
20650 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
20660 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
20670 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
20680 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
20690 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
206a0 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
206b0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
206c0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
206d0 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
206e0 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
206f0 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
20700 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
20710 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
20720 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
20730 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
20740 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
20750 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
20760 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
20770 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
20780 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
20790 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
207a0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
207b0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
207c0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
207d0 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
207e0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
207f0 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
20800 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
20810 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
20820 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
20830 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
20840 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  t..*/.sqlite3_in
20850 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
20860 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73  ry_used(void);.s
20870 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
20880 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
20890 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
208a0 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
208b0 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
208c0 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
208d0 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
208e0 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
208f0 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
20900 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
20910 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
20920 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
20930 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
20940 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
20950 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
20960 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
20970 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
20980 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
20990 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
209a0 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
209b0 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
209c0 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
209d0 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
209e0 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
209f0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
20a00 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
20a10 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
20a20 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
20a30 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
20a40 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
20a50 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
20a60 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
20a70 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
20a80 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
20a90 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50  fer P..** ^The P
20aa0 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62   parameter can b
20ab0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
20ac0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73  ..**.** ^If this
20ad0 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74   routine has not
20ae0 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79   been previously
20af0 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68   called or if th
20b00 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61  e previous.** ca
20b10 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68  ll had N less th
20b20 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c  an one or a NULL
20b30 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20   pointer for P, 
20b40 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73  then the PRNG is
20b50 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67  .** seeded using
20b60 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
20b70 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52  ined from the xR
20b80 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64  andomness method
20b90 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75   of.** the defau
20ba0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
20bb0 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20   object..** ^If 
20bc0 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
20bd0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
20be0 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20  e had an N of 1 
20bf0 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a  or more and a.**
20c00 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e   non-NULL P then
20c10 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
20c20 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
20c30 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
20c40 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
20c50 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
20c60 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
20c70 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
20c80 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
20c90 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
20ca0 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
20cb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20cc0 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
20cd0 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
20ce0 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
20cf0 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45 59 57 4f  sqlite3.** KEYWO
20d00 52 44 53 3a 20 7b 61 75 74 68 6f 72 69 7a 65 72  RDS: {authorizer
20d10 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a   callback}.**.**
20d20 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
20d30 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
20d40 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
20d50 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
20d60 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
20d70 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
20d80 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
20d90 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
20da0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
20db0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
20dc0 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
20dd0 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
20de0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
20df0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
20e00 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
20e10 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
20e20 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
20e30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
20e40 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
20e50 65 70 61 72 65 31 36 28 29 5d 2c 20 5b 73 71 6c  epare16()], [sql
20e60 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
20e70 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71  2()],.** and [sq
20e80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
20e90 76 33 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69  v3()].  ^At vari
20ea0 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
20eb0 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
20ec0 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
20ed0 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
20ee0 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
20ef0 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
20f00 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
20f10 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
20f20 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
20f30 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
20f40 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
20f50 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  .  ^The authoriz
20f60 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
20f70 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
20f80 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
20f90 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
20fa0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
20fb0 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
20fc0 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
20fd0 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
20fe0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
20ff0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
21000 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
21010 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
21020 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
21030 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
21040 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
21050 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
21060 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
21070 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
21080 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
21090 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
210a0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
210b0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
210c0 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
210d0 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
210e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
210f0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
21100 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
21110 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
21120 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
21130 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
21140 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
21150 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
21160 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
21170 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
21180 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
21190 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e  uested is ok.  ^
211a0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
211b0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
211c0 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
211d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
211e0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
211f0 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
21200 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
21210 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
21220 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
21230 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
21240 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
21250 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
21260 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
21270 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
21280 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
21290 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
212a0 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
212b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
212c0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
212d0 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
212e0 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e  face. ^The secon
212f0 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
21300 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
21310 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
21320 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
21330 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
21340 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
21350 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
21360 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
21370 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68  d. ^The third th
21380 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
21390 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
213a0 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 65 69   callback are ei
213b0 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ther NULL pointe
213c0 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65 72 6d 69  rs or zero-termi
213d0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a  nated strings.**
213e0 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
213f0 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73  ditional details
21400 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
21410 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
21420 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  ed..** Applicati
21430 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61 79 73 20  ons must always 
21440 62 65 20 70 72 65 70 61 72 65 64 20 74 6f 20 65  be prepared to e
21450 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55 4c 4c 20  ncounter a NULL 
21460 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e 79 0a 2a  pointer in any.*
21470 2a 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 74  * of the third t
21480 68 72 6f 75 67 68 20 74 68 65 20 73 69 78 74 68  hrough the sixth
21490 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
214a0 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
214b0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
214c0 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
214d0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
214e0 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
214f0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
21500 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
21510 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
21520 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21530 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
21540 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
21550 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
21560 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
21570 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
21580 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
21590 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
215a0 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
215b0 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
215c0 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
215d0 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
215e0 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
215f0 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
21600 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
21610 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
21620 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
21630 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e 20  table..** ^When 
21640 61 20 74 61 62 6c 65 20 69 73 20 72 65 66 65 72  a table is refer
21650 65 6e 63 65 64 20 62 79 20 61 20 5b 53 45 4c 45  enced by a [SELE
21660 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f 6c 75 6d  CT] but no colum
21670 6e 20 76 61 6c 75 65 73 20 61 72 65 0a 2a 2a 20  n values are.** 
21680 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 20 74  extracted from t
21690 68 61 74 20 74 61 62 6c 65 20 28 66 6f 72 20 65  hat table (for e
216a0 78 61 6d 70 6c 65 20 69 6e 20 61 20 71 75 65 72  xample in a quer
216b0 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c 45 43  y like.** "SELEC
216c0 54 20 63 6f 75 6e 74 28 2a 29 20 46 52 4f 4d 20  T count(*) FROM 
216d0 74 61 62 22 29 20 74 68 65 6e 20 74 68 65 20 5b  tab") then the [
216e0 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 75 74  SQLITE_READ] aut
216f0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21700 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  .** is invoked o
21710 6e 63 65 20 66 6f 72 20 74 68 61 74 20 74 61 62  nce for that tab
21720 6c 65 20 77 69 74 68 20 61 20 63 6f 6c 75 6d 6e  le with a column
21730 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 61 6e   name that is an
21740 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a   empty string..*
21750 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
21760 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
21770 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
21780 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
21790 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
217a0 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
217b0 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
217c0 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
217d0 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
217e0 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
217f0 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
21800 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
21810 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
21820 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
21830 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
21840 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21850 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
21860 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
21870 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
21880 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
21890 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
218a0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
218b0 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
218c0 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
218d0 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
218e0 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
218f0 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
21900 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
21910 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
21920 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
21930 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
21940 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
21950 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
21960 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
21970 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
21980 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
21990 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
219a0 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
219b0 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
219c0 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
219d0 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
219e0 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
219f0 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
21a00 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
21a10 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
21a20 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
21a30 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
21a40 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
21a50 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
21a60 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
21a70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
21a80 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
21a90 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
21aa0 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
21ab0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
21ac0 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
21ad0 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
21ae0 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
21af0 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
21b00 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
21b10 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
21b20 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
21b30 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
21b40 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
21b50 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
21b60 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
21b70 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
21b80 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
21b90 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
21ba0 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
21bb0 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73  **.** ^(Only a s
21bc0 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
21bd0 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
21be0 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
21bf0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
21c00 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
21c10 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
21c20 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
21c30 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
21c40 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20  evious call.)^  
21c50 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74  ^Disable the aut
21c60 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
21c70 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
21c80 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
21c90 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
21ca0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
21cb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
21cc0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
21cd0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
21ce0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
21cf0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
21d00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
21d10 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
21d20 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21d30 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
21d40 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
21d50 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
21d60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
21d70 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
21d80 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
21d90 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
21da0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
21db0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
21dc0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57  agraph..**.** ^W
21dd0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
21de0 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73  pare_v2()] is us
21df0 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
21e00 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
21e10 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
21e20 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64  t be re-prepared
21e30 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
21e40 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
21e50 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
21e60 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
21e70 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
21e80 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
21e90 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
21ea0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
21eb0 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
21ec0 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
21ed0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
21ee0 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
21ef0 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
21f00 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
21f10 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
21f20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
21f30 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
21f40 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
21f50 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
21f60 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
21f70 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
21f80 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
21f90 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
21fa0 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
21fb0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
21fc0 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
21fd0 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
21fe0 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
21ff0 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65  epare_v2() to re
22000 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
22010 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
22020 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e  ma change..*/.in
22030 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
22040 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
22050 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
22060 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
22070 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
22080 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
22090 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
220a0 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
220b0 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
220c0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
220d0 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a  r Return Codes.*
220e0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
220f0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
22100 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
22110 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
22120 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
22130 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
22140 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
22150 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
22160 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
22170 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
22180 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
22190 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
221a0 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
221b0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
221c0 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
221d0 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
221e0 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
221f0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
22200 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ion..**.** Note 
22210 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f  that SQLITE_IGNO
22220 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  RE is also used 
22230 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72  as a [conflict r
22240 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a  esolution mode].
22250 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ** returned from
22260 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74   the [sqlite3_vt
22270 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
22280 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
22290 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
222a0 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
222b0 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
222c0 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
222d0 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
222e0 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
222f0 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
22300 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
22310 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
22320 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
22330 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
22340 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
22350 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
22360 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
22370 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
22380 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
22390 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
223a0 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
223b0 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
223c0 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
223d0 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
223e0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
223f0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
22400 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
22410 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
22420 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
22430 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
22440 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
22450 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
22460 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
22470 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
22480 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
22490 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
224a0 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
224b0 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
224c0 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
224d0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
224e0 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
224f0 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
22500 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
22510 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
22520 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
22530 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
22540 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
22550 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
22560 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
22570 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
22580 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
22590 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
225a0 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
225b0 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
225c0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
225d0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
225e0 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
225f0 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
22600 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
22610 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
22620 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
22630 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
22640 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
22650 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
22660 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
22670 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
22680 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
22690 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
226a0 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
226b0 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
226c0 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
226d0 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
226e0 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
226f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22700 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22710 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
22720 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
22730 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
22740 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
22750 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
22760 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
22770 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
22780 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
22790 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
227a0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
227b0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
227c0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
227d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
227e0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
227f0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
22800 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
22810 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
22820 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22830 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
22840 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
22850 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22860 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22870 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22880 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
22890 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
228a0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
228b0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
228c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
228d0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
228e0 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
228f0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
22900 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22910 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22920 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
22930 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
22940 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
22950 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22960 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22970 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
22980 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
22990 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
229a0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
229b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
229c0 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
229d0 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
229e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
229f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22a00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22a10 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
22a20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
22a30 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
22a40 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22a50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22a60 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
22a70 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
22a80 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
22a90 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22aa0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22ab0 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
22ac0 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
22ad0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
22ae0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
22af0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22b00 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
22b10 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
22b20 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
22b30 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22b40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22b50 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
22b60 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
22b70 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
22b80 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
22b90 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
22ba0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
22bb0 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
22bc0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
22bd0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22be0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
22bf0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
22c00 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
22c10 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
22c20 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
22c30 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
22c40 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
22c50 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
22c60 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
22c70 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22c80 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
22c90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
22ca0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22cb0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22cc0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22cd0 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
22ce0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
22cf0 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
22d00 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
22d10 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
22d20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
22d30 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
22d40 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22d50 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
22d60 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22d70 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
22d80 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
22d90 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
22da0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22db0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22dc0 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
22dd0 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
22de0 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
22df0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22e00 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22e10 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
22e20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
22e30 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22e40 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
22e50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22e60 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
22e70 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
22e80 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
22e90 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22ea0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22eb0 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
22ec0 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
22ed0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
22ee0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22ef0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22f00 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
22f10 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
22f20 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
22f30 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22f40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22f50 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
22f60 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
22f70 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
22f80 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22f90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
22fa0 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
22fb0 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
22fc0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
22fd0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22fe0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
22ff0 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
23000 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
23010 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
23020 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
23030 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
23040 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
23050 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
23060 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
23070 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
23080 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
23090 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
230a0 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
230b0 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
230c0 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
230d0 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
230e0 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
230f0 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
23100 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
23110 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
23120 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
23130 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23140 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
23150 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
23160 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56   SQLITE_RECURSIV
23170 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20  E            33 
23180 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
23190 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
231a0 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43       */../*.** C
231b0 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
231c0 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
231d0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48  unctions.** METH
231e0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
231f0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
23200 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e   are deprecated.
23210 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
23220 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e  3_trace_v2()] in
23230 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65  terface.** inste
23240 61 64 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e  ad of the routin
23250 65 73 20 64 65 73 63 72 69 62 65 64 20 68 65 72  es described her
23260 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e..**.** These r
23270 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
23280 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
23290 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
232a0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
232b0 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
232c0 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
232d0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
232e0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  s..**.** ^The ca
232f0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
23300 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
23310 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
23320 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
23330 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
23340 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
23350 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
23360 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
23370 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
23380 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
23390 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
233a0 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65   with a UTF-8 re
233b0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a  ndering of the.*
233c0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
233d0 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74  text as the stat
233e0 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
233f0 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  ns executing..**
23400 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71   ^(Additional sq
23410 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
23420 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63  llbacks might oc
23430 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
23440 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
23450 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
23460 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
23470 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
23480 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
23490 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
234a0 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
234b0 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  rigger.)^.**.** 
234c0 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  The [SQLITE_TRAC
234d0 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f  E_SIZE_LIMIT] co
234e0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
234f0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
23500 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65   limit.** the le
23510 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70  ngth of [bound p
23520 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73  arameter] expans
23530 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75  ion in the outpu
23540 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61  t of sqlite3_tra
23550 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ce()..**.** ^The
23560 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
23570 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
23580 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
23590 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
235a0 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
235b0 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
235c0 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
235d0 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
235e0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
235f0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
23600 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
23610 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
23620 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
23630 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
23640 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e   took to run.  ^
23650 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
23660 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20  back.** time is 
23670 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f  in units of nano
23680 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72  seconds, however
23690 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
236a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
236b0 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f  s only capable o
236c0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65  f millisecond re
236d0 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20  solution so the 
236e0 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66  six least signif
236f0 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20  icant.** digits 
23700 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20  in the time are 
23710 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75  meaningless.  Fu
23720 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
23730 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74   SQLite.** might
23740 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72   provide greater
23750 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74   resolution on t
23760 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c  he profiler call
23770 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71  back.  The.** sq
23780 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
23790 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73  function is cons
237a0 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
237b0 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75  tal and is.** su
237c0 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
237d0 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
237e0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
237f0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
23800 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  ED void *sqlite3
23810 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
23820 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 61 63 65  .   void(*xTrace
23830 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
23840 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
23850 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
23860 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
23870 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
23880 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
23890 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
238a0 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
238b0 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
238c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
238d0 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20 43  QL Trace Event C
238e0 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
238f0 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a  : SQLITE_TRACE.*
23900 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
23910 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63 6c  ants identify cl
23920 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73 20  asses of events 
23930 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69  that can be moni
23940 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74  tored.** using t
23950 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  he [sqlite3_trac
23960 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67 20  e_v2()] tracing 
23970 6c 6f 67 69 63 2e 20 20 54 68 65 20 4d 20 61 72  logic.  The M ar
23980 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71  gument.** to [sq
23990 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44  lite3_trace_v2(D
239a0 2c 4d 2c 58 2c 50 29 5d 20 69 73 20 61 6e 20 4f  ,M,X,P)] is an O
239b0 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  R-ed combination
239c0 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
239d0 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
239e0 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20  ing constants.  
239f0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
23a00 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65  ent to the trace
23a10 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
23a20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
23a30 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a  wing constants..
23a40 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e  **.** New tracin
23a50 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20  g constants may 
23a60 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
23a70 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a  re releases..**.
23a80 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c  ** ^A trace call
23a90 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20 61 72  back has four ar
23aa0 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61  guments: xCallba
23ab0 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20  ck(T,C,P,X)..** 
23ac0 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20  ^The T argument 
23ad0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e  is one of the in
23ae0 74 65 67 65 72 20 74 79 70 65 20 63 6f 64 65 73  teger type codes
23af0 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20   above..** ^The 
23b00 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  C argument is a 
23b10 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
23b20 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61 73 73  ext pointer pass
23b30 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
23b40 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
23b50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  to [sqlite3_trac
23b60 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  e_v2()]..** The 
23b70 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74  P and X argument
23b80 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77  s are pointers w
23b90 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65  hose meanings de
23ba0 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a  pend on T..**.**
23bb0 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
23bc0 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c  E_TRACE_STMT]] <
23bd0 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  dt>SQLITE_TRACE_
23be0 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  STMT</dt>.** <dd
23bf0 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43  >^An SQLITE_TRAC
23c00 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20  E_STMT callback 
23c10 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
23c20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
23c30 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62 65  ment.** first be
23c40 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  gins running and
23c50 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f 74 68   possibly at oth
23c60 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e 67 20  er times during 
23c70 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e  the.** execution
23c80 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64   of the prepared
23c90 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75 63 68   statement, such
23ca0 20 61 73 20 61 74 20 74 68 65 20 73 74 61 72 74   as at the start
23cb0 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72 69 67   of each.** trig
23cc0 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 20  ger subprogram. 
23cd0 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
23ce0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
23cf0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
23d00 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68   statement]. ^Th
23d10 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e X argument is 
23d20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73  a pointer to a s
23d30 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69  tring which.** i
23d40 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64 65 64  s the unexpanded
23d50 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74 68 65   SQL text of the
23d60 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
23d70 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f  ent or an SQL co
23d80 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69  mment .** that i
23d90 6e 64 69 63 61 74 65 73 20 74 68 65 20 69 6e 76  ndicates the inv
23da0 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74 72 69  ocation of a tri
23db0 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c  gger.  ^The call
23dc0 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65  back can compute
23dd0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 65 78  .** the same tex
23de0 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  t that would hav
23df0 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 20  e been returned 
23e00 62 79 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  by the legacy [s
23e10 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 0a  qlite3_trace()].
23e20 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  ** interface by 
23e30 75 73 69 6e 67 20 74 68 65 20 58 20 61 72 67 75  using the X argu
23e40 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65 67 69  ment when X begi
23e50 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61 6e 64  ns with "--" and
23e60 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71   invoking.** [sq
23e70 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
23e80 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69 73 65  ql(P)] otherwise
23e90 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
23ea0 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d  _TRACE_PROFILE]]
23eb0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
23ec0 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a  E_PROFILE</dt>.*
23ed0 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45  * <dd>^An SQLITE
23ee0 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63  _TRACE_PROFILE c
23ef0 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64 65 73  allback provides
23f00 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 74   approximately t
23f10 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72  he same.** infor
23f20 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70 72 6f  mation as is pro
23f30 76 69 64 65 64 20 62 79 20 74 68 65 20 5b 73 71  vided by the [sq
23f40 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d  lite3_profile()]
23f50 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54   callback..** ^T
23f60 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
23f70 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
23f80 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
23f90 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a  ement] and the.*
23fa0 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  * X argument poi
23fb0 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69 74 20  nts to a 64-bit 
23fc0 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
23fd0 20 74 68 65 20 65 73 74 69 6d 61 74 65 64 20 6f   the estimated o
23fe0 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  f.** the number 
23ff0 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68  of nanosecond th
24000 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  at the prepared 
24010 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74  statement took t
24020 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53  o run..** ^The S
24030 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46  QLITE_TRACE_PROF
24040 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ILE callback is 
24050 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
24060 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
24070 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  hes..**.** [[SQL
24080 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20  ITE_TRACE_ROW]] 
24090 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45  <dt>SQLITE_TRACE
240a0 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ROW</dt>.** <dd
240b0 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43  >^An SQLITE_TRAC
240c0 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69  E_ROW callback i
240d0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  s invoked whenev
240e0 65 72 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a  er a prepared.**
240f0 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72   statement gener
24100 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20 72 6f  ates a single ro
24110 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a  w of result.  .*
24120 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  * ^The P argumen
24130 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
24140 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
24150 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74  statement] and t
24160 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74  he.** X argument
24170 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a   is unused..**.*
24180 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  * [[SQLITE_TRACE
24190 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c  _CLOSE]] <dt>SQL
241a0 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c  ITE_TRACE_CLOSE<
241b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20  /dt>.** <dd>^An 
241c0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f  SQLITE_TRACE_CLO
241d0 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  SE callback is i
241e0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 64 61  nvoked when a da
241f0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
24200 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20  tion closes..** 
24210 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
24220 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
24230 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
24240 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74  nnection] object
24250 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20 61 72  .** and the X ar
24260 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64  gument is unused
24270 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ..** </dl>.*/.#d
24280 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
24290 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20 30 78  CE_STMT       0x
242a0 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
242b0 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20  E_TRACE_PROFILE 
242c0 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20     0x02.#define 
242d0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57  SQLITE_TRACE_ROW
242e0 20 20 20 20 20 20 20 20 30 78 30 34 0a 23 64 65          0x04.#de
242f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43  fine SQLITE_TRAC
24300 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30 78 30  E_CLOSE      0x0
24310 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  8../*.** CAPI3RE
24320 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48 6f 6f  F: SQL Trace Hoo
24330 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  k.** METHOD: sql
24340 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
24350 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
24360 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,M,X,P) interf
24370 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
24380 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  trace callback.*
24390 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61 67 61  * function X aga
243a0 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65 20 63  inst [database c
243b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73  onnection] D, us
243c0 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d 61 73  ing property mas
243d0 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65  k M.** and conte
243e0 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e  xt pointer P.  ^
243f0 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62 61 63  If the X callbac
24400 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20  k is.** NULL or 
24410 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20 69 73  if the M mask is
24420 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 61 63   zero, then trac
24430 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ing is disabled.
24440 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d    The.** M argum
24450 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
24460 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65 64 20  e bitwise OR-ed 
24470 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
24480 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b  * zero or more [
24490 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20 63 6f  SQLITE_TRACE] co
244a0 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  nstants..**.** ^
244b0 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65 69 74  Each call to eit
244c0 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63  her sqlite3_trac
244d0 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74  e() or sqlite3_t
244e0 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72 72 69  race_v2() overri
244f0 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73  des .** (cancels
24500 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c  ) any prior call
24510 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61  s to sqlite3_tra
24520 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  ce() or sqlite3_
24530 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  trace_v2()..**.*
24540 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62 61 63  * ^The X callbac
24550 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
24560 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74 68 65  never any of the
24570 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69 66 69   events identifi
24580 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d  ed by .** mask M
24590 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20 69 6e   occur.  ^The in
245a0 74 65 67 65 72 20 72 65 74 75 72 6e 20 76 61 6c  teger return val
245b0 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c  ue from the call
245c0 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e 74 6c  back is currentl
245d0 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68  y.** ignored, th
245e0 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20 63 68  ough this may ch
245f0 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 72  ange in future r
24600 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c 62 61  eleases.  Callba
24610 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ck.** implementa
24620 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65 74  tions should ret
24630 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75  urn zero to ensu
24640 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70 61 74  re future compat
24650 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ibility..**.** ^
24660 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  A trace callback
24670 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
24680 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a   four arguments:
24690 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c   callback(T,C,P,
246a0 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72  X)..** ^The T ar
246b0 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
246c0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41   the [SQLITE_TRA
246d0 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73  CE].** constants
246e0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 79   to indicate why
246f0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61   the callback wa
24700 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54  s invoked..** ^T
24710 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73  he C argument is
24720 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63   a copy of the c
24730 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a  ontext pointer..
24740 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 61  ** The P and X a
24750 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69  rguments are poi
24760 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e  nters whose mean
24770 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54  ings depend on T
24780 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
24790 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 69  te3_trace_v2() i
247a0 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
247b0 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63 65 20  nded to replace 
247c0 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
247d0 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
247e0 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64 20 5b  3_trace()] and [
247f0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
24800 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68 69 63  )], both of whic
24810 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65 63 61  h.** are depreca
24820 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ted..*/.int sqli
24830 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a 20 20  te3_trace_v2(.  
24840 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69  sqlite3*,.  unsi
24850 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e  gned uMask,.  in
24860 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e  t(*xCallback)(un
24870 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69  signed,void*,voi
24880 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69  d*,void*),.  voi
24890 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a  d *pCtx.);../*.*
248a0 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
248b0 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
248c0 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
248d0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
248e0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  he sqlite3_progr
248f0 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c  ess_handler(D,N,
24900 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63  X,P) interface c
24910 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61  auses the callba
24920 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
24930 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70   to be invoked p
24940 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
24950 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
24960 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
24970 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
24980 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
24990 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  nd [sqlite3_get_
249a0 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20  table()] for.** 
249b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
249c0 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70  ion D.  An examp
249d0 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a  le use for this.
249e0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
249f0 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
24a00 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
24a10 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
24a20 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72  * ^The parameter
24a30 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72   P is passed thr
24a40 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79  ough as the only
24a50 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
24a60 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  e .** callback f
24a70 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65  unction X.  ^The
24a80 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20   parameter N is 
24a90 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20  the approximate 
24aa0 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76  number of .** [v
24ab0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69  irtual machine i
24ac0 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61  nstructions] tha
24ad0 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t are evaluated 
24ae0 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69  between successi
24af0 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  ve.** invocation
24b00 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  s of the callbac
24b10 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c  k X.  ^If N is l
24b20 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65  ess than one the
24b30 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a  n the progress.*
24b40 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73  * handler is dis
24b50 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  abled..**.** ^On
24b60 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
24b70 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79  ress handler may
24b80 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f   be defined at o
24b90 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b  ne time per.** [
24ba0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24bb0 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20  ion]; setting a 
24bc0 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e  new progress han
24bd0 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65  dler cancels the
24be0 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53  .** old one.  ^S
24bf0 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72  etting parameter
24c00 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62   X to NULL disab
24c10 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73  les the progress
24c20 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68   handler..** ^Th
24c30 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
24c40 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62  er is also disab
24c50 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e  led by setting N
24c60 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73   to a value less
24c70 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a  .** than 1..**.*
24c80 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65  * ^If the progre
24c90 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
24ca0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
24cb0 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
24cc0 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
24cd0 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
24ce0 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
24cf0 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
24d00 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
24d10 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61  GUI progress dia
24d20 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54  log box..**.** T
24d30 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
24d40 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  ler callback mus
24d50 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
24d60 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
24d70 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
24d80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
24d90 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
24da0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
24db0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
24dc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
24dd0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
24de0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
24df0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
24e00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24e10 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
24e20 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
24e30 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
24e40 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71  h..**.*/.void sq
24e50 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
24e60 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
24e70 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
24e80 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
24e90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
24ea0 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
24eb0 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
24ec0 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20  ** CONSTRUCTOR: 
24ed0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
24ee0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
24ef0 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
24f00 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70  abase file as sp
24f10 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ecified by the .
24f20 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
24f30 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e  ment. ^The filen
24f40 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
24f50 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
24f60 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
24f70 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
24f80 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
24f90 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
24fa0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
24fb0 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
24fc0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
24fd0 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63   ^(A [database c
24fe0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
24ff0 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
25000 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
25010 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
25020 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
25030 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
25040 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
25050 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
25060 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
25070 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
25080 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
25090 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
250a0 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
250b0 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
250c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
250d0 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
250e0 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65  ject.)^ ^(If the
250f0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
25100 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
25110 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
25120 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
25130 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
25140 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
25150 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
25160 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54  s returned.)^ ^T
25170 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
25180 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
25190 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
251a0 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
251b0 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
251c0 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
251d0 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
251e0 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  on of the error 
251f0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
25200 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ure of any.** of
25210 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   the sqlite3_ope
25220 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  n() routines..**
25230 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
25240 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62   encoding will b
25250 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61  e UTF-8 for data
25260 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73  bases created us
25270 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  ing.** sqlite3_o
25280 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
25290 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68  _open_v2().  ^Th
252a0 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
252b0 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73  ng for databases
252c0 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e  .** created usin
252d0 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  g sqlite3_open16
252e0 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31  () will be UTF-1
252f0 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
25300 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a  byte order..**.*
25310 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
25320 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
25330 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
25340 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
25350 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
25360 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
25370 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
25380 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
25390 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
253a0 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
253b0 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
253c0 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
253d0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
253e0 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
253f0 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
25400 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
25410 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
25420 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
25430 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
25440 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
25450 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
25460 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
25470 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
25480 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65  nnection.  ^(The
25490 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
254a0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   to.** sqlite3_o
254b0 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b  pen_v2() can tak
254c0 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
254d0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
254e0 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
254f0 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
25500 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
25510 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
25520 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
25530 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  LMUTEX], [SQLITE
25540 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
25550 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  E],.** [SQLITE_O
25560 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
25570 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ], and/or [SQLIT
25580 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
25590 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
255a0 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
255b0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
255c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
255d0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
255e0 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
255f0 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
25600 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
25610 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
25620 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
25630 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
25640 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
25650 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
25660 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
25670 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
25680 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
25690 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
256a0 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
256b0 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
256c0 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
256d0 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
256e0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
256f0 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
25700 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
25710 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
25720 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
25730 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
25740 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
25750 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
25760 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
25770 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
25780 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
25790 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
257a0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
257b0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
257c0 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
257d0 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20  reated if.** it 
257e0 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
257f0 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
25800 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
25810 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
25820 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
25830 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
25840 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
25850 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  >)^.** </dl>.**.
25860 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
25870 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
25880 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
25890 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
258a0 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
258b0 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f  hown above optio
258c0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
258d0 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51  ith other.** [SQ
258e0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
258f0 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e  LY | SQLITE_OPEN
25900 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e  _* bits].** then
25910 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
25920 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
25930 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
25940 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
25950 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65  flag is set, the
25960 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
25970 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65  onnection.** ope
25980 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d  ns in the multi-
25990 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
259a0 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20  g mode] as long 
259b0 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68  as the single-th
259c0 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73  read.** mode has
259d0 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74   not been set at
259e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
259f0 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49   start-time.  ^I
25a00 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
25a10 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
25a20 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
25a30 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
25a40 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
25a50 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
25a60 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
25a70 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
25a80 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
25a90 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
25aa0 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
25ab0 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
25ac0 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ime..** ^The [SQ
25ad0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
25ae0 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
25af0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
25b00 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65  connection to be
25b10 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20  .** eligible to 
25b20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68  use [shared cach
25b30 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c  e mode], regardl
25b40 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
25b50 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20  r not shared.** 
25b60 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
25b70 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
25b80 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
25b90 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a  che()].  ^The.**
25ba0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
25bb0 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
25bc0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
25bd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
25be0 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63  to not.** partic
25bf0 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64  ipate in [shared
25c00 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65   cache mode] eve
25c10 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c  n if it is enabl
25c20 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
25c30 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
25c40 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
25c50 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
25c60 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
25c70 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
25c80 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
25c90 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
25ca0 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
25cb0 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
25cc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
25cd0 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66  should use.  ^If
25ce0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
25cf0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
25d00 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
25d10 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
25d20 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
25d30 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
25d40 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
25d50 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
25d60 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
25d70 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
25d80 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
25d90 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
25da0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
25db0 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
25dc0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
25dd0 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
25de0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
25df0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
25e00 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
25e10 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
25e20 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
25e30 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
25e40 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
25e50 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
25e60 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
25e70 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
25e80 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
25e90 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
25ea0 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
25eb0 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
25ec0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
25ed0 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
25ee0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
25ef0 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
25f00 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
25f10 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
25f20 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
25f30 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
25f40 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
25f50 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
25f60 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
25f70 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
25f80 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
25f90 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
25fa0 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
25fb0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
25fc0 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
25fd0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
25fe0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
25ff0 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  d..**.** [[URI f
26000 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69  ilenames in sqli
26010 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33  te3_open()]] <h3
26020 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f  >URI Filenames</
26030 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55  h3>.**.** ^If [U
26040 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74  RI filename] int
26050 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
26060 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20  nabled, and the 
26070 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
26080 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68  t.** begins with
26090 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74   "file:", then t
260a0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69  he filename is i
260b0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
260c0 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c  URI. ^URI.** fil
260d0 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
260e0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20  tion is enabled 
260f0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
26100 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
26110 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 74  .** set in the t
26120 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
26130 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
26140 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73  (), or if it has
26150 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64  .** been enabled
26160 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20   globally using 
26170 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
26180 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77  IG_URI] option w
26190 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ith the.** [sqli
261a0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65  te3_config()] me
261b0 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b  thod or by the [
261c0 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
261d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
261e0 69 6f 6e 2e 0a 2a 2a 20 55 52 49 20 66 69 6c 65  ion..** URI file
261f0 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
26200 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66  ion is turned of
26210 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c  f.** by default,
26220 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65   but future rele
26230 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ases of SQLite m
26240 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20  ight enable URI 
26250 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65  filename.** inte
26260 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65  rpretation by de
26270 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52  fault.  See "[UR
26280 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f  I filenames]" fo
26290 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
262a0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
262b0 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  ** URI filenames
262c0 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f   are parsed acco
262d0 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38  rding to RFC 398
262e0 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63  6. ^If the URI c
262f0 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75  ontains an.** au
26300 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74  thority, then it
26310 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
26320 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
26330 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a  or the string .*
26340 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e  * "localhost". ^
26350 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  If the authority
26360 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79   is not an empty
26370 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61   string or "loca
26380 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65  lhost", an .** e
26390 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
263a0 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20   to the caller. 
263b0 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f  ^The fragment co
263c0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
263d0 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74  , if .** present
263e0 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  , is ignored..**
263f0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
26400 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e   the path compon
26410 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61  ent of the URI a
26420 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
26430 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77  e disk file.** w
26440 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68  hich contains th
26450 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20  e database. ^If 
26460 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20  the path begins 
26470 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61  with a '/' chara
26480 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69  cter, .** then i
26490 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
264a0 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   as an absolute 
264b0 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61  path. ^If the pa
264c0 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69  th does not begi
264d0 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27  n .** with a '/'
264e0 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74   (meaning that t
264f0 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63  he authority sec
26500 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20  tion is omitted 
26510 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a  from the URI).**
26520 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69   then the path i
26530 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
26540 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68   a relative path
26550 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f  . .** ^(On windo
26560 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f  ws, the first co
26570 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62  mponent of an ab
26580 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20  solute path .** 
26590 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69  is a drive speci
265a0 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22  fication (e.g. "
265b0 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  C:").)^.**.** [[
265c0 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70  core URI query p
265d0 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54  arameters]].** T
265e0 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
265f0 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20  nt of a URI may 
26600 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65  contain paramete
26610 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  rs that are inte
26620 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65  rpreted.** eithe
26630 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65  r by SQLite itse
26640 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53  lf, or by a [VFS
26650 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d   | custom VFS im
26660 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a  plementation]..*
26670 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73  * SQLite and its
26680 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73   built-in [VFSes
26690 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a  ] interpret the.
266a0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65  ** following que
266b0 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a  ry parameters:.*
266c0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  *.** <ul>.**   <
266d0 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20  li> <b>vfs</b>: 
266e0 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d  ^The "vfs" param
266f0 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64  eter may be used
26700 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
26710 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61  name of.**     a
26720 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74   VFS object that
26730 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70   provides the op
26740 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
26750 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68  nterface that sh
26760 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75  ould.**     be u
26770 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68  sed to access th
26780 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
26790 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69  on disk. ^If thi
267a0 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  s option is set 
267b0 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70  to.**     an emp
267c0 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65  ty string the de
267d0 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74  fault VFS object
267e0 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69   is used. ^Speci
267f0 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
26800 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61  .**     VFS is a
26810 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c  n error. ^If sql
26820 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
26830 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76  s used and the v
26840 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  fs option is.** 
26850 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65      present, the
26860 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66  n the VFS specif
26870 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f  ied by the optio
26880 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e  n takes preceden
26890 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74  ce over.**     t
268a0 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
268b0 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  as the fourth pa
268c0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
268d0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
268e0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f  .**   <li> <b>mo
268f0 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f  de</b>: ^(The mo
26900 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  de parameter may
26910 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
26920 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a  r "ro", "rw",.**
26930 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22       "rwc", or "
26940 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74  memory". Attempt
26950 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f  ing to set it to
26960 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65   any other value
26970 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72   is.**     an er
26980 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e  ror)^. .**     ^
26990 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69  If "ro" is speci
269a0 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64  fied, then the d
269b0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
269c0 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  d for read-only 
269d0 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
269e0 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b  just as if the [
269f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
26a00 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62  ONLY] flag had b
26a10 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a  een set in the .
26a20 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67  **     third arg
26a30 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
26a40 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20  _open_v2(). ^If 
26a50 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
26a60 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20  is set to .**   
26a70 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65    "rw", then the
26a80 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
26a90 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69  ned for read-wri
26aa0 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61  te (but not crea
26ab0 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  te) .**     acce
26ac0 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45  ss, as if SQLITE
26ad0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
26ae0 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f  (but not SQLITE_
26af0 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64  OPEN_CREATE) had
26b00 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65   .**     been se
26b10 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20  t. ^Value "rwc" 
26b20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
26b30 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a   setting both .*
26b40 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
26b50 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20  N_READWRITE and 
26b60 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
26b70 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64  TE.  ^If the mod
26b80 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  e option is.**  
26b90 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72     set to "memor
26ba0 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b  y" then a pure [
26bb0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
26bc0 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72  se] that never r
26bd0 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77  eads.**     or w
26be0 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20  rites from disk 
26bf0 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20  is used. ^It is 
26c00 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63  an error to spec
26c10 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a  ify a value for.
26c20 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20  **     the mode 
26c30 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69  parameter that i
26c40 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69  s less restricti
26c50 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65  ve than that spe
26c60 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
26c70 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65   the flags passe
26c80 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70  d in the third p
26c90 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
26ca0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
26cb0 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63  *.**   <li> <b>c
26cc0 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63  ache</b>: ^The c
26cd0 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d  ache parameter m
26ce0 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
26cf0 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a  her "shared" or.
26d00 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22  **     "private"
26d10 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f  . ^Setting it to
26d20 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75   "shared" is equ
26d30 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
26d40 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51  ng the.**     SQ
26d50 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
26d60 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65  CACHE bit in the
26d70 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
26d80 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20  passed to.**    
26d90 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
26da0 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65  (). ^Setting the
26db0 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
26dc0 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73   to "private" is
26dd0 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c   .**     equival
26de0 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
26df0 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  he SQLITE_OPEN_P
26e00 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e  RIVATECACHE bit.
26e10 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69  .**     ^If sqli
26e20 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
26e30 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63   used and the "c
26e40 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20  ache" parameter 
26e50 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a  is present in.**
26e60 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e       a URI filen
26e70 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f  ame, its value o
26e80 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68  verrides any beh
26e90 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20  avior requested 
26ea0 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20  by setting.**   
26eb0 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52    SQLITE_OPEN_PR
26ec0 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51  IVATECACHE or SQ
26ed0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
26ee0 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a  CACHE flag..**.*
26ef0 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c  *  <li> <b>psow<
26f00 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70  /b>: ^The psow p
26f10 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74  arameter indicat
26f20 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  es whether or no
26f30 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f  t the.**     [po
26f40 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74  wersafe overwrit
26f50 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73  e] property does
26f60 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70   or does not app
26f70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  ly to the.**    
26f80 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f   storage media o
26f90 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61  n which the data
26fa0 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65  base file reside
26fb0 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  s..**.**  <li> <
26fc0 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54  b>nolock</b>: ^T
26fd0 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65  he nolock parame
26fe0 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  ter is a boolean
26ff0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
27000 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66  .**     which if
27010 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69   set disables fi
27020 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f  le locking in ro
27030 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d  llback journal m
27040 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20  odes.  This.**  
27050 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72     is useful for
27060 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74   accessing a dat
27070 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73  abase on a files
27080 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20  ystem that does 
27090 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f  not.**     suppo
270a0 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75  rt locking.  Cau
270b0 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20  tion:  Database 
270c0 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74  corruption might
270d0 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a   result if two.*
270e0 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72  *     or more pr
270f0 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f  ocesses write to
27100 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
27110 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f  se and any one o
27120 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70  f those.**     p
27130 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f  rocesses uses no
27140 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c  lock=1..**.**  <
27150 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65  li> <b>immutable
27160 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74  </b>: ^The immut
27170 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69  able parameter i
27180 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72  s a boolean quer
27190 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74  y.**     paramet
271a0 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  er that indicate
271b0 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
271c0 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72  ase file is stor
271d0 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61  ed on.**     rea
271e0 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e  d-only media.  ^
271f0 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69  When immutable i
27200 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73  s set, SQLite as
27210 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
27220 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66  *     database f
27230 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  ile cannot be ch
27240 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61  anged, even by a
27250 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69   process with hi
27260 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76  gher.**     priv
27270 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68  ilege, and so th
27280 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
27290 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61  ened read-only a
272a0 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a  nd all locking.*
272b0 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65  *     and change
272c0 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69   detection is di
272d0 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e  sabled.  Caution
272e0 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d  : Setting the im
272f0 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70  mutable.**     p
27300 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74  roperty on a dat
27310 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20  abase file that 
27320 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61  does in fact cha
27330 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a  nge can result.*
27340 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65  *     in incorre
27350 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  ct query results
27360 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
27370 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e  CORRUPT] errors.
27380 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f  .**     See also
27390 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  : [SQLITE_IOCAP_
273a0 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20  IMMUTABLE]..**  
273b0 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a       .** </ul>.*
273c0 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67  *.** ^Specifying
273d0 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61   an unknown para
273e0 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65  meter in the que
273f0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
27400 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a  a URI is not an.
27410 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72  ** error.  Futur
27420 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
27430 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72  Lite might under
27440 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c  stand additional
27450 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
27460 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65  ters.  See "[que
27470 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69  ry parameters wi
27480 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69  th special meani
27490 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66  ng to SQLite]" f
274a0 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  or.** additional
274b0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
274c0 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
274d0 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68  me examples]] <h
274e0 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  3>URI filename e
274f0 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  xamples</h3>.**.
27500 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
27510 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65  ="1" align=cente
27520 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e  r cellpadding=5>
27530 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49  .** <tr><th> URI
27540 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20   filenames <th> 
27550 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c  Results.** <tr><
27560 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
27570 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
27580 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65     Open the file
27590 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
275a0 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
275b0 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ory..** <tr><td>
275c0 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
275d0 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20  /data.db<br>.** 
275e0 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
275f0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
27600 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20  db <br> .**     
27610 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61       file://loca
27620 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f  lhost/home/fred/
27630 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64  data.db <br> <td
27640 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
27650 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
27660 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
27670 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c  d/data.db"..** <
27680 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64  tr><td> file://d
27690 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65  arkstar/home/fre
276a0 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  d/data.db <td> .
276b0 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
276c0 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22  rror. "darkstar"
276d0 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e   is not a recogn
276e0 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a  ized authority..
276f0 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65  ** <tr><td style
27700 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f  ="white-space:no
27710 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20  wrap"> .**      
27720 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44      file:///C:/D
27730 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32  ocuments%20and%2
27740 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44  0Settings/fred/D
27750 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a  esktop/data.db.*
27760 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f  *     <td> Windo
27770 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68  ws only: Open th
27780 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
27790 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74   on fred's deskt
277a0 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20  op on drive.**  
277b0 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65          C:. Note
277c0 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73   that the %20 es
277d0 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65  caping in this e
277e0 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74  xample is not st
277f0 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20  rictly .**      
27800 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20      necessary - 
27810 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73  space characters
27820 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74   can be used lit
27830 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20  erally.**       
27840 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61     in URI filena
27850 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  mes..** <tr><td>
27860 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
27870 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76  de=ro&cache=priv
27880 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  ate <td> .**    
27890 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
278a0 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
278b0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
278c0 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ry for read-only
278d0 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20   access..**     
278e0 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20       Regardless 
278f0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
27900 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d  t shared-cache m
27910 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62  ode is enabled b
27920 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65  y.**          de
27930 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69  fault, use a pri
27940 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c  vate cache..** <
27950 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
27960 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f  me/fred/data.db?
27970 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65  vfs=unix-dotfile
27980 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20   <td>.**        
27990 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f    Open file "/ho
279a0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
279b0 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61  . Use the specia
279c0 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66  l VFS "unix-dotf
279d0 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20  ile".**         
279e0 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66   that uses dot-f
279f0 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66  iles in place of
27a00 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20   posix advisory 
27a10 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e  locking..** <tr>
27a20 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
27a30 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20  b?mode=readonly 
27a40 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
27a50 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61    An error. "rea
27a60 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20  donly" is not a 
27a70 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72  valid option for
27a80 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61   the "mode" para
27a90 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c  meter..** </tabl
27aa0 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65  e>.**.** ^URI he
27ab0 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
27ac0 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29   sequences (%HH)
27ad0 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77   are supported w
27ae0 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61  ithin the path a
27af0 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70  nd.** query comp
27b00 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e  onents of a URI.
27b10 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65   A hexadecimal e
27b20 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63  scape sequence c
27b30 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20  onsists of a.** 
27b40 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22  percent sign - "
27b50 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79  %" - followed by
27b60 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78   exactly two hex
27b70 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20  adecimal digits 
27b80 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61  .** specifying a
27b90 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e  n octet value. ^
27ba0 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20  Before the path 
27bb0 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  or query compone
27bc0 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20  nts of a.** URI 
27bd0 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74  filename are int
27be0 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61  erpreted, they a
27bf0 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  re encoded using
27c00 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a   UTF-8 and all .
27c10 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  ** hexadecimal e
27c20 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
27c30 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69  replaced by a si
27c40 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69  ngle byte contai
27c50 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72  ning the.** corr
27c60 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e  esponding octet.
27c70 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73   If this process
27c80 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e   generates an in
27c90 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f  valid UTF-8 enco
27ca0 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73  ding,.** the res
27cb0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
27cc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
27cd0 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
27ce0 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
27cf0 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
27d00 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
27d10 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
27d20 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
27d30 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
27d40 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
27d50 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
27d60 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
27d70 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
27d80 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
27d90 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
27da0 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
27db0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
27dc0 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
27dd0 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
27de0 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
27df0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
27e00 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
27e10 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
27e20 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75  indows Runtime u
27e30 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74  sers:</b>  The t
27e40 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f  emporary directo
27e50 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a  ry must be set.*
27e60 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  * prior to calli
27e70 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ng sqlite3_open(
27e80 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
27e90 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69  n_v2().  Otherwi
27ea0 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66  se, various.** f
27eb0 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71  eatures that req
27ec0 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20  uire the use of 
27ed0 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20  temporary files 
27ee0 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20  may fail..**.** 
27ef0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
27f00 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
27f10 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  y].*/.int sqlite
27f20 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
27f30 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
27f40 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
27f50 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
27f60 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
27f70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
27f80 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
27f90 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
27fa0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
27fb0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
27fc0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
27fd0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
27fe0 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
27ff0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
28000 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
28010 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
28020 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
28030 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
28040 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
28050 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
28060 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
28070 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
28080 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
28090 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
280a0 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
280b0 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
280c0 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
280d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
280e0 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
280f0 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
28100 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
28110 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
28120 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52  in Values For UR
28130 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  I Parameters.**.
28140 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69  ** These are uti
28150 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75  lity routines, u
28160 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70  seful to VFS imp
28170 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68  lementations, th
28180 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73  at check.** to s
28190 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65  ee if a database
281a0 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20   file was a URI 
281b0 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61  that contained a
281c0 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20   specific query 
281d0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61  .** parameter, a
281e0 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73  nd if so obtains
281f0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
28200 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  at query paramet
28210 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69  er..**.** If F i
28220 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
28230 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  ilename pointer 
28240 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
28250 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f  xOpen() method o
28260 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c  f .** a VFS impl
28270 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20  ementation when 
28280 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  the flags parame
28290 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68  ter to xOpen() h
282a0 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f  as one or .** mo
282b0 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  re of the [SQLIT
282c0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b  E_OPEN_URI] or [
282d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
282e0 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e  _DB] bits set an
282f0 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61  d.** P is the na
28300 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  me of the query 
28310 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a  parameter, then.
28320 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  ** sqlite3_uri_p
28330 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
28340 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20  turns the value 
28350 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61  of the P.** para
28360 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73  meter if it exis
28370 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ts or a NULL poi
28380 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e  nter if P does n
28390 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a  ot appear as a .
283a0 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ** query paramet
283b0 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69  er on F.  If P i
283c0 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65  s a query parame
283d0 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20  ter of F.** has 
283e0 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75  no explicit valu
283f0 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
28400 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
28410 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  P) returns.** a 
28420 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d  pointer to an em
28430 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  pty string..**.*
28440 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72  * The sqlite3_ur
28450 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
28460 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73   routine assumes
28470 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f   that P is a boo
28480 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65  lean.** paramete
28490 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72  r and returns tr
284a0 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20  ue (1) or false 
284b0 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  (0) according to
284c0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66   the value.** of
284d0 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33   P.  The sqlite3
284e0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
284f0 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,B) routine retu
28500 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20  rns true (1) if 
28510 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
28520 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
28530 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73  P is one of "yes
28540 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f  ", "true", or "o
28550 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73  n" in any.** cas
28560 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  e or if the valu
28570 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  e begins with a 
28580 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e  non-zero number.
28590 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65    The .** sqlite
285a0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
285b0 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65  P,B) routines re
285c0 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20  turns false (0) 
285d0 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a  if the value of.
285e0 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ** query paramet
285f0 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22  er P is one of "
28600 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72  no", "false", or
28610 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61   "off" in any ca
28620 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20  se or.** if the 
28630 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
28640 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f  h a numeric zero
28650 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61  .  If P is not a
28660 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
28670 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74  ter on F or if t
28680 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
28690 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20   does not match 
286a0 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62  any of the.** ab
286b0 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ove, then sqlite
286c0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
286d0 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21  P,B) returns (B!
286e0 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  =0)..**.** The s
286f0 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
28700 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20  (F,P,D) routine 
28710 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c  converts the val
28720 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a  ue of P into a.*
28730 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  * 64-bit signed 
28740 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75  integer and retu
28750 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72  rns that integer
28760 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73  , or D if P does
28770 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20   not.** exist.  
28780 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  If the value of 
28790 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f  P is something o
287a0 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74  ther than an int
287b0 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65  eger, then.** ze
287c0 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
287d0 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61  ** .** If F is a
287e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
287f0 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
28800 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
28810 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a  eturns NULL and.
28820 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
28830 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
28840 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69  turns B.  If F i
28850 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69  s not a NULL poi
28860 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e  nter and.** is n
28870 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
28880 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e  le pathname poin
28890 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  ter that SQLite 
288a0 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
288b0 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74  xOpen.** VFS met
288c0 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65  hod, then the be
288d0 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72  havior of this r
288e0 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69  outine is undefi
288f0 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
28900 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  .** undesirable.
28910 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
28920 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
28930 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72  meter(const char
28940 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e   *zFilename, con
28950 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29  st char *zParam)
28960 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72  ;.int sqlite3_ur
28970 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20  i_boolean(const 
28980 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e  char *zFile, con
28990 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c  st char *zParam,
289a0 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a   int bDefault);.
289b0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
289c0 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
289d0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e  const char*, con
289e0 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
289f0 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a  3_int64);.../*.*
28a00 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
28a10 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
28a20 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ages.** METHOD: 
28a30 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49  sqlite3.**.** ^I
28a40 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
28a50 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20  t sqlite3_* API 
28a60 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20  call associated 
28a70 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61  with .** [databa
28a80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
28a90 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68   failed, then th
28aa0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
28ab0 65 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  e(D) interface.*
28ac0 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  * returns the nu
28ad0 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
28ae0 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  de] or [extended
28af0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f   result code] fo
28b00 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61  r that.** API ca
28b10 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f  ll..** If the mo
28b20 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61  st recent API ca
28b30 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73 66 75  ll was successfu
28b40 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  l,.** then the r
28b50 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
28b60 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
28b70 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
28b80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
28b90 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
28ba0 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
28bb0 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63   is the same exc
28bc0 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61  ept that it alwa
28bd0 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a  ys returns the .
28be0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
28bf0 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77  ult code] even w
28c00 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
28c10 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a  ult codes are.**
28c20 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
28c30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
28c40 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
28c50 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
28c60 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
28c70 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
28c80 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
28c90 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
28ca0 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
28cb0 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
28cc0 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
28cd0 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
28ce0 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
28cf0 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
28d00 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
28d10 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
28d20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62  need to worry ab
28d30 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20  out freeing the 
28d40 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76  result..** Howev
28d50 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74  er, the error st
28d60 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76  ring might be ov
28d70 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
28d80 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73  llocated by.** s
28d90 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
28da0 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  to other SQLite 
28db0 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
28dc0 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ons.)^.**.** ^Th
28dd0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72  e sqlite3_errstr
28de0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
28df0 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68  urns the English
28e00 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a  -language text.*
28e10 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  * that describes
28e20 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64   the [result cod
28e30 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a  e], as UTF-8..**
28e40 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
28e50 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
28e60 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
28e70 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
28e80 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74  .** and must not
28e90 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65   be freed by the
28ea0 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a   application)^..
28eb0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73  **.** When the s
28ec0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
28ed0 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e  ding mode] is in
28ee0 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62   use, it might b
28ef0 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68  e the.** case th
28f00 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f  at a second erro
28f10 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65  r occurs on a se
28f20 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e  parate thread in
28f30 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
28f40 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73  time of the firs
28f50 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20  t error and the 
28f60 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e  call to these in
28f70 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65  terfaces..** Whe
28f80 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20  n that happens, 
28f90 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  the second error
28fa0 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65   will be reporte
28fb0 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a  d since these.**
28fc0 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61   interfaces alwa
28fd0 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f  ys report the mo
28fe0 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74  st recent result
28ff0 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74  .  To avoid.** t
29000 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64  his, each thread
29010 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c   can obtain excl
29020 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65  usive use of the
29030 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
29040 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69  ction] D.** by i
29050 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
29060 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73  _mutex_enter]([s
29070 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
29080 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69  (D)) before begi
29090 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20  nning.** to use 
290a0 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b  D and invoking [
290b0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
290c0 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ave]([sqlite3_db
290d0 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65  _mutex](D)) afte
290e0 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74  r.** all calls t
290f0 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73  o the interfaces
29100 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65   listed here are
29110 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a   completed..**.*
29120 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63  * If an interfac
29130 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c  e fails with SQL
29140 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74  ITE_MISUSE, that
29150 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72   means the inter
29160 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f  face.** was invo
29170 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ked incorrectly 
29180 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
29190 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73  on.  In that cas
291a0 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20  e, the.** error 
291b0 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
291c0 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20   may or may not 
291d0 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73  be set..*/.int s
291e0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73  qlite3_errcode(s
291f0 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74  qlite3 *db);.int
29200 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
29210 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  d_errcode(sqlite
29220 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68  3 *db);.const ch
29230 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  ar *sqlite3_errm
29240 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  sg(sqlite3*);.co
29250 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
29260 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74  3_errmsg16(sqlit
29270 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  e3*);.const char
29280 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72   *sqlite3_errstr
29290 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
292a0 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 64  PI3REF: Prepared
292b0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
292c0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
292d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
292e0 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74  nt} {prepared st
292f0 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20  atements}.**.** 
29300 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
29310 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
29320 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53  sents a single S
29330 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
29340 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 6f  t.** has been co
29350 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61  mpiled into bina
29360 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72  ry form and is r
29370 65 61 64 79 20 74 6f 20 62 65 20 65 76 61 6c 75  eady to be evalu
29380 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e  ated..**.** Thin
29390 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20 73 74  k of each SQL st
293a0 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73 65 70  atement as a sep
293b0 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72 20 70  arate computer p
293c0 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20  rogram.  The.** 
293d0 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
293e0 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  t is source code
293f0 2e 20 20 41 20 70 72 65 70 61 72 65 64 20 73 74  .  A prepared st
29400 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a  atement object .
29410 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 69 6c  ** is the compil
29420 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20  ed object code. 
29430 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 65   All SQL must be
29440 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
29450 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  a.** prepared st
29460 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 69  atement before i
29470 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a  t can be run..**
29480 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 63  .** The life-cyc
29490 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64  le of a prepared
294a0 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
294b0 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c  t usually goes l
294c0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
294d0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
294e0 61 74 65 20 74 68 65 20 70 72 65 70 61 72 65 64  ate the prepared
294f0 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
29500 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
29510 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a  _prepare_v2()]..
29520 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c  ** <li> Bind val
29530 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  ues to [paramete
29540 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
29550 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
29560 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
29570 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
29580 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
29590 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
295a0 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
295b0 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
295c0 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
295d0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
295e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
295f0 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
29600 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
29610 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
29620 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
29630 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
29640 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
29650 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
29660 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
29670 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
29680 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73  t sqlite3_stmt s
29690 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a  qlite3_stmt;../*
296a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
296b0 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a  n-time Limits.**
296c0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
296d0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e  .**.** ^(This in
296e0 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74  terface allows t
296f0 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f  he size of vario
29700 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  us constructs to
29710 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f   be limited.** o
29720 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  n a connection b
29730 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  y connection bas
29740 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  is.  The first p
29750 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
29760 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
29770 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c  nection] whose l
29780 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65  imit is to be se
29790 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54  t or queried.  T
297a0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
297b0 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66  ameter is one of
297c0 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65   the [limit cate
297d0 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66  gories] that def
297e0 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f  ine a.** class o
297f0 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  f constructs to 
29800 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e  be size limited.
29810 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
29820 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
29830 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68  new limit for th
29840 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a  at construct.)^.
29850 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65  **.** ^If the ne
29860 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67  w limit is a neg
29870 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68  ative number, th
29880 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61  e limit is uncha
29890 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65  nged..** ^(For e
298a0 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ach limit catego
298b0 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ry SQLITE_LIMIT_
298c0 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72  <i>NAME</i> ther
298d0 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69  e is a .** [limi
298e0 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20  ts | hard upper 
298f0 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74  bound].** set at
29900 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79   compile-time by
29910 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f   a C preprocesso
29920 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a  r macro called.*
29930 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49  * [limits | SQLI
29940 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f  TE_MAX_<i>NAME</
29950 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c  i>]..** (The "_L
29960 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61  IMIT_" in the na
29970 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f  me is changed to
29980 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20   "_MAX_".))^.** 
29990 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63  ^Attempts to inc
299a0 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62  rease a limit ab
299b0 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70  ove its hard upp
299c0 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20  er bound are.** 
299d0 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
299e0 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75  ed to the hard u
299f0 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a  pper bound..**.*
29a00 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66  * ^Regardless of
29a10 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
29a20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68  the limit was ch
29a30 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b  anged, the .** [
29a40 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
29a50 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
29a60 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ns the prior val
29a70 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e  ue of the limit.
29a80 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66  .** ^Hence, to f
29a90 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20  ind the current 
29aa0 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74  value of a limit
29ab0 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e   without changin
29ac0 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20  g it,.** simply 
29ad0 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65  invoke this inte
29ae0 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74  rface with the t
29af0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73  hird parameter s
29b00 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20  et to -1..**.** 
29b10 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20  Run-time limits 
29b20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
29b30 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74   use in applicat
29b40 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65  ions that manage
29b50 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f  .** both their o
29b60 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  wn internal data
29b70 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61  base and also da
29b80 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65  tabases that are
29b90 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62   controlled.** b
29ba0 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65  y untrusted exte
29bb0 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41  rnal sources.  A
29bc0 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63  n example applic
29bd0 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61  ation might be a
29be0 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20  .** web browser 
29bf0 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e  that has its own
29c00 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73   databases for s
29c10 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61  toring history a
29c20 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64  nd.** separate d
29c30 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c  atabases control
29c40 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70  led by JavaScrip
29c50 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64  t applications d
29c60 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66  ownloaded.** off
29c70 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20   the Internet.  
29c80 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  The internal dat
29c90 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69  abases can be gi
29ca0 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65  ven the.** large
29cb0 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73  , default limits
29cc0 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e  .  Databases man
29cd0 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c  aged by external
29ce0 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20   sources can.** 
29cf0 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d  be given much sm
29d00 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73  aller limits des
29d10 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74  igned to prevent
29d20 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72   a denial of ser
29d30 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20  vice.** attack. 
29d40 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68   Developers migh
29d50 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75  t also want to u
29d60 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
29d70 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
29d80 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74  ].** interface t
29d90 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f  o further contro
29da0 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e  l untrusted SQL.
29db0 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
29dc0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72  e database.** cr
29dd0 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72  eated by an untr
29de0 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e  usted script can
29df0 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73   be contained us
29e00 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f  ing the.** [max_
29e10 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
29e20 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  GMA]..**.** New 
29e30 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63  run-time limit c
29e40 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65  ategories may be
29e50 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
29e60 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e   releases..*/.in
29e70 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28  t sqlite3_limit(
29e80 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64  sqlite3*, int id
29e90 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a  , int newVal);..
29ea0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29eb0 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43  Run-Time Limit C
29ec0 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59  ategories.** KEY
29ed0 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
29ee0 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20  tegory} {*limit 
29ef0 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a  categories}.**.*
29f00 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
29f10 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
29f20 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d   performance lim
29f30 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  its.** that can 
29f40 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75  be lowered at ru
29f50 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71  n-time using [sq
29f60 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a  lite3_limit()]..
29f70 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20  ** The synopsis 
29f80 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20  of the meanings 
29f90 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  of the various l
29fa0 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62  imits is shown b
29fb0 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  elow..** Additio
29fc0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  nal information 
29fd0 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20  is available at 
29fe0 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73  [limits | Limits
29ff0 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a   in SQLite]..**.
2a000 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
2a010 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
2a020 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2a030 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74  LIMIT_LENGTH</dt
2a040 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2a050 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79  imum size of any
2a060 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
2a070 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e  or table row, in
2a080 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a   bytes.<dd>)^.**
2a090 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2a0a0 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20  IT_SQL_LENGTH]] 
2a0b0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2a0c0 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64  IT_SQL_LENGTH</d
2a0d0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2a0e0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2a0f0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
2a100 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e  , in bytes.</dd>
2a110 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2a120 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d  E_LIMIT_COLUMN]]
2a130 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2a140 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a  MIT_COLUMN</dt>.
2a150 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2a160 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
2a170 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20  umns in a table 
2a180 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e  definition or in
2a190 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73   the.** result s
2a1a0 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
2a1b0 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   or the maximum 
2a1c0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2a1d0 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a  s in an index.**
2a1e0 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20   or in an ORDER 
2a1f0 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63  BY or GROUP BY c
2a200 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  lause.</dd>)^.**
2a210 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2a220 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20  IT_EXPR_DEPTH]] 
2a230 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2a240 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64  IT_EXPR_DEPTH</d
2a250 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2a260 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74  ximum depth of t
2a270 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e  he parse tree on
2a280 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e   any expression.
2a290 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2a2a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
2a2b0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e  POUND_SELECT]] ^
2a2c0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2a2d0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
2a2e0 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
2a2f0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2a300 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63   of terms in a c
2a310 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73  ompound SELECT s
2a320 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e  tatement.</dd>)^
2a330 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2a340 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20  LIMIT_VDBE_OP]] 
2a350 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2a360 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a  IT_VDBE_OP</dt>.
2a370 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2a380 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73  um number of ins
2a390 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76  tructions in a v
2a3a0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70  irtual machine p
2a3b0 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74  rogram.** used t
2a3c0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53  o implement an S
2a3d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  QL statement.  I
2a3e0 66 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  f [sqlite3_prepa
2a3f0 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 74  re_v2()] or.** t
2a400 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 74 72  he equivalent tr
2a410 69 65 73 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ies to allocate 
2a420 73 70 61 63 65 20 66 6f 72 20 6d 6f 72 65 20 74  space for more t
2a430 68 61 6e 20 74 68 69 73 20 6d 61 6e 79 20 6f 70  han this many op
2a440 63 6f 64 65 73 0a 2a 2a 20 69 6e 20 61 20 73 69  codes.** in a si
2a450 6e 67 6c 65 20 70 72 65 70 61 72 65 64 20 73 74  ngle prepared st
2a460 61 74 65 6d 65 6e 74 2c 20 61 6e 20 53 51 4c 49  atement, an SQLI
2a470 54 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f 72 20 69  TE_NOMEM error i
2a480 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
2a490 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2a4a0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
2a4b0 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  _ARG]] ^(<dt>SQL
2a4c0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
2a4d0 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  ON_ARG</dt>.** <
2a4e0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
2a4f0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2a500 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e  ts on a function
2a510 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2a520 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  [SQLITE_LIMIT_AT
2a530 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53  TACHED]] ^(<dt>S
2a540 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
2a550 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHED</dt>.** <dd
2a560 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
2a570 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c  ber of [ATTACH |
2a580 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
2a590 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  ses].)^</dd>.**.
2a5a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2a5b0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
2a5c0 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  ENGTH]].** ^(<dt
2a5d0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  >SQLITE_LIMIT_LI
2a5e0 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
2a5f0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
2a600 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
2a610 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20   of the pattern 
2a620 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
2a630 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c  [LIKE] or.** [GL
2a640 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  OB] operators.</
2a650 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2a660 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
2a670 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20  BLE_NUMBER]].** 
2a680 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2a690 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
2a6a0 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ER</dt>.** <dd>T
2a6b0 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78  he maximum index
2a6c0 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b   number of any [
2a6d0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e  parameter] in an
2a6e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29   SQL statement.)
2a6f0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2a700 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
2a710 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
2a720 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
2a730 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
2a740 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2a750 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69  depth of recursi
2a760 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e  on for triggers.
2a770 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2a780 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52  SQLITE_LIMIT_WOR
2a790 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28  KER_THREADS]] ^(
2a7a0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2a7b0 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 3c  _WORKER_THREADS<
2a7c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2a7d0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
2a7e0 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72 6b  f auxiliary work
2a7f0 65 72 20 74 68 72 65 61 64 73 20 74 68 61 74 20  er threads that 
2a800 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65  a single.** [pre
2a810 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a820 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e   may start.</dd>
2a830 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  )^.** </dl>.*/.#
2a840 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2a850 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  MIT_LENGTH      
2a860 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a                0.
2a870 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2a880 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20  IMIT_SQL_LENGTH 
2a890 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
2a8a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a8b0 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20  LIMIT_COLUMN    
2a8c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a8d0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2a8e0 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
2a8f0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
2a900 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
2a910 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
2a920 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
2a930 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
2a940 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
2a950 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a960 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
2a970 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
2a980 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20  ON_ARG          
2a990 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
2a9a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
2a9b0 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20  HED             
2a9c0 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
2a9d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
2a9e0 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20  _PATTERN_LENGTH 
2a9f0 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
2aa00 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
2aa10 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20  IABLE_NUMBER    
2aa20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
2aa30 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52   SQLITE_LIMIT_TR
2aa40 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20  IGGER_DEPTH     
2aa50 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e         10.#defin
2aa60 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57  e SQLITE_LIMIT_W
2aa70 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20 20  ORKER_THREADS   
2aa80 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a          11../*.*
2aa90 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 70  * CAPI3REF: Prep
2aaa0 61 72 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  are Flags.**.** 
2aab0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
2aac0 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 66  define various f
2aad0 6c 61 67 73 20 74 68 61 74 20 63 61 6e 20 62 65  lags that can be
2aae0 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
2aaf0 22 70 72 65 70 46 6c 61 67 73 22 20 70 61 72 61  "prepFlags" para
2ab00 6d 65 74 65 72 20 6f 66 20 74 68 65 20 5b 73 71  meter of the [sq
2ab10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2ab20 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
2ab30 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
2ab40 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  ()] interfaces..
2ab50 2a 2a 0a 2a 2a 20 4e 65 77 20 66 6c 61 67 73 20  **.** New flags 
2ab60 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
2ab70 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
2ab80 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
2ab90 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
2aba0 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53  E_PREPARE_PERSIS
2abb0 54 45 4e 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  TENT]] ^(<dt>SQL
2abc0 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53  ITE_PREPARE_PERS
2abd0 49 53 54 45 4e 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  ISTENT</dt>.** <
2abe0 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 50 52  dd>The SQLITE_PR
2abf0 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54  EPARE_PERSISTENT
2ac00 20 66 6c 61 67 20 69 73 20 61 20 68 69 6e 74 20   flag is a hint 
2ac10 74 6f 20 74 68 65 20 71 75 65 72 79 20 70 6c 61  to the query pla
2ac20 6e 6e 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  nner.** that the
2ac30 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2ac40 65 6e 74 20 77 69 6c 6c 20 62 65 20 72 65 74 61  ent will be reta
2ac50 69 6e 65 64 20 66 6f 72 20 61 20 6c 6f 6e 67 20  ined for a long 
2ac60 74 69 6d 65 20 61 6e 64 0a 2a 2a 20 70 72 6f 62  time and.** prob
2ac70 61 62 6c 79 20 72 65 75 73 65 64 20 6d 61 6e 79  ably reused many
2ac80 20 74 69 6d 65 73 2e 29 5e 20 5e 57 69 74 68 6f   times.)^ ^Witho
2ac90 75 74 20 74 68 69 73 20 66 6c 61 67 2c 20 5b 73  ut this flag, [s
2aca0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2acb0 33 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  3()].** and [sql
2acc0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2acd0 33 28 29 5d 20 61 73 73 75 6d 65 20 74 68 61 74  3()] assume that
2ace0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2acf0 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 0a 2a 2a  atement will .**
2ad00 20 62 65 20 75 73 65 64 20 6a 75 73 74 20 6f 6e   be used just on
2ad10 63 65 20 6f 72 20 61 74 20 6d 6f 73 74 20 61 20  ce or at most a 
2ad20 66 65 77 20 74 69 6d 65 73 20 61 6e 64 20 74 68  few times and th
2ad30 65 6e 20 64 65 73 74 72 6f 79 65 64 20 75 73 69  en destroyed usi
2ad40 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
2ad50 69 6e 61 6c 69 7a 65 28 29 5d 20 72 65 6c 61 74  inalize()] relat
2ad60 69 76 65 6c 79 20 73 6f 6f 6e 2e 20 54 68 65 20  ively soon. The 
2ad70 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
2ad80 74 61 74 69 6f 6e 20 61 63 74 73 0a 2a 2a 20 6f  tation acts.** o
2ad90 6e 20 74 68 69 73 20 68 69 6e 74 20 62 79 20 61  n this hint by a
2ada0 76 6f 69 64 69 6e 67 20 74 68 65 20 75 73 65 20  voiding the use 
2adb0 6f 66 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  of [lookaside me
2adc0 6d 6f 72 79 5d 20 73 6f 20 61 73 20 6e 6f 74 20  mory] so as not 
2add0 74 6f 0a 2a 2a 20 64 65 70 6c 65 74 65 20 74 68  to.** deplete th
2ade0 65 20 6c 69 6d 69 74 65 64 20 73 74 6f 72 65 20  e limited store 
2adf0 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  of lookaside mem
2ae00 6f 72 79 2e 20 46 75 74 75 72 65 20 76 65 72 73  ory. Future vers
2ae10 69 6f 6e 73 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ions of.** SQLit
2ae20 65 20 6d 61 79 20 61 63 74 20 6f 6e 20 74 68 69  e may act on thi
2ae30 73 20 68 69 6e 74 20 64 69 66 66 65 72 65 6e 74  s hint different
2ae40 6c 79 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  ly..** </dl>.*/.
2ae50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
2ae60 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e  REPARE_PERSISTEN
2ae70 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  T              0
2ae80 78 30 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  x01../*.** CAPI3
2ae90 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
2aea0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
2aeb0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
2aec0 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
2aed0 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  iler}.** METHOD:
2aee0 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53   sqlite3.** CONS
2aef0 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
2af00 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  _stmt.**.** To e
2af10 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 73 74  xecute an SQL st
2af20 61 74 65 6d 65 6e 74 2c 20 69 74 20 6d 75 73 74  atement, it must
2af30 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
2af40 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
2af50 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
2af60 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
2af70 65 20 72 6f 75 74 69 6e 65 73 2e 20 20 4f 72 2c  e routines.  Or,
2af80 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   in other words,
2af90 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
2afa0 2a 2a 20 61 72 65 20 63 6f 6e 73 74 72 75 63 74  ** are construct
2afb0 6f 72 73 20 66 6f 72 20 74 68 65 20 5b 70 72 65  ors for the [pre
2afc0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2afd0 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54   object..**.** T
2afe0 68 65 20 70 72 65 66 65 72 72 65 64 20 72 6f 75  he preferred rou
2aff0 74 69 6e 65 20 74 6f 20 75 73 65 20 69 73 20 5b  tine to use is [
2b000 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2b010 76 32 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 5b  v2()].  The.** [
2b020 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2b030 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  )] interface is 
2b040 6c 65 67 61 63 79 20 61 6e 64 20 73 68 6f 75 6c  legacy and shoul
2b050 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a  d be avoided..**
2b060 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b070 65 5f 76 33 28 29 5d 20 68 61 73 20 61 6e 20 65  e_v3()] has an e
2b080 78 74 72 61 20 22 70 72 65 70 46 6c 61 67 73 22  xtra "prepFlags"
2b090 20 6f 70 74 69 6f 6e 20 74 68 61 74 20 69 73 20   option that is 
2b0a0 75 73 65 64 0a 2a 2a 20 66 6f 72 20 73 70 65 63  used.** for spec
2b0b0 69 61 6c 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  ial purposes..**
2b0c0 0a 2a 2a 20 54 68 65 20 75 73 65 20 6f 66 20 74  .** The use of t
2b0d0 68 65 20 55 54 46 2d 38 20 69 6e 74 65 72 66 61  he UTF-8 interfa
2b0e0 63 65 73 20 69 73 20 70 72 65 66 65 72 72 65 64  ces is preferred
2b0f0 2c 20 61 73 20 53 51 4c 69 74 65 20 63 75 72 72  , as SQLite curr
2b100 65 6e 74 6c 79 0a 2a 2a 20 64 6f 65 73 20 61 6c  ently.** does al
2b110 6c 20 70 61 72 73 69 6e 67 20 75 73 69 6e 67 20  l parsing using 
2b120 55 54 46 2d 38 2e 20 20 54 68 65 20 55 54 46 2d  UTF-8.  The UTF-
2b130 31 36 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  16 interfaces ar
2b140 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 61 73  e provided.** as
2b150 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 2e 20   a convenience. 
2b160 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65   The UTF-16 inte
2b170 72 66 61 63 65 73 20 77 6f 72 6b 20 62 79 20 63  rfaces work by c
2b180 6f 6e 76 65 72 74 69 6e 67 20 74 68 65 0a 2a 2a  onverting the.**
2b190 20 69 6e 70 75 74 20 74 65 78 74 20 69 6e 74 6f   input text into
2b1a0 20 55 54 46 2d 38 2c 20 74 68 65 6e 20 69 6e 76   UTF-8, then inv
2b1b0 6f 6b 69 6e 67 20 74 68 65 20 63 6f 72 72 65 73  oking the corres
2b1c0 70 6f 6e 64 69 6e 67 20 55 54 46 2d 38 20 69 6e  ponding UTF-8 in
2b1d0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
2b1e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2b1f0 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
2b200 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2b210 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
2b220 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
2b230 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
2b240 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
2b250 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
2b260 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
2b270 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
2b280 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
2b290 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
2b2a0 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
2b2b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
2b2c0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
2b2d0 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
2b2e0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
2b2f0 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
2b300 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
2b310 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
2b320 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
2b330 72 65 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72  re(), sqlite3_pr
2b340 65 70 61 72 65 5f 76 32 28 29 2c 0a 2a 2a 20 61  epare_v2(),.** a
2b350 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
2b360 72 65 5f 76 33 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v3().** inter
2b370 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
2b380 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2b390 70 61 72 65 31 36 28 29 2c 20 73 71 6c 69 74 65  pare16(), sqlite
2b3a0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2b3b0 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  ,.** and sqlite3
2b3c0 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 20  _prepare16_v3() 
2b3d0 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
2b3e0 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20  * ^If the nByte 
2b3f0 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61  argument is nega
2b400 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20  tive, then zSql 
2b410 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
2b420 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
2b430 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20  terminator. ^If 
2b440 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74 69 76  nByte is positiv
2b450 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
2b460 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
2b470 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
2b480 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20  Sql.  ^If nByte 
2b490 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f  is zero, then no
2b4a0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2b4b0 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61  tement is genera
2b4c0 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63  ted..** If the c
2b4d0 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74  aller knows that
2b4e0 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
2b4f0 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
2b500 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20  inated, then.** 
2b510 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
2b520 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
2b530 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e  antage to passin
2b540 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
2b550 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
2b560 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2b570 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
2b580 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
2b590 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
2b5a0 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  nul-terminator..
2b5b0 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c  **.** ^If pzTail
2b5c0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
2b5d0 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
2b5e0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
2b5f0 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20  e first byte.** 
2b600 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
2b610 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
2b620 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
2b630 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
2b640 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65   only.** compile
2b650 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
2b660 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
2b670 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
2b680 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20   pointing to.** 
2b690 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
2b6a0 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ompiled..**.** ^
2b6b0 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
2b6c0 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
2b6d0 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
2b6e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2b6f0 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
2b700 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
2b710 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66  e3_step()].  ^If
2b720 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
2b730 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
2b740 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
2b750 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65  ^If the input te
2b760 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
2b770 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
2b780 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
2b790 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
2b7a0 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
2b7b0 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
2b7c0 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67  ..** The calling
2b7d0 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
2b7e0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
2b7f0 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
2b800 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
2b810 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
2b820 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2b830 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
2b840 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
2b850 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74  * ppStmt may not
2b860 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
2b870 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65  ^On success, the
2b880 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2b890 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75  () family of rou
2b8a0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
2b8b0 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68  LITE_OK];.** oth
2b8c0 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
2b8d0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
2b8e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
2b8f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2b900 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70  (), sqlite3_prep
2b910 61 72 65 5f 76 33 28 29 2c 20 73 71 6c 69 74 65  are_v3(), sqlite
2b920 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2b930 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  ,.** and sqlite3
2b940 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 20  _prepare16_v3() 
2b950 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
2b960 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61  ecommended for a
2b970 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e  ll new programs.
2b980 0a 2a 2a 20 54 68 65 20 6f 6c 64 65 72 20 69 6e  .** The older in
2b990 74 65 72 66 61 63 65 73 20 28 73 71 6c 69 74 65  terfaces (sqlite
2b9a0 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
2b9b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2b9c0 36 28 29 29 0a 2a 2a 20 61 72 65 20 72 65 74 61  6()).** are reta
2b9d0 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  ined for backwar
2b9e0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
2b9f0 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
2ba00 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
2ba10 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 58 22 20  ** ^In the "vX" 
2ba20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
2ba30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ba40 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65  nt.** that is re
2ba50 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c  turned (the [sql
2ba60 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
2ba70 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  t) contains a co
2ba80 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69  py of the.** ori
2ba90 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
2baa0 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20  This causes the 
2bab0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2bac0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
2bad0 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e   behave differen
2bae0 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79  tly in three way
2baf0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
2bb00 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
2bb10 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
2bb20 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
2bb30 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
2bb40 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
2bb50 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
2bb60 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
2bb70 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
2bb80 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
2bb90 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
2bba0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
2bbb0 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
2bbc0 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61  again. As many a
2bbd0 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43  s [SQLITE_MAX_SC
2bbe0 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72  HEMA_RETRY].** r
2bbf0 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75  etries will occu
2bc00 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  r before sqlite3
2bc10 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70  _step() gives up
2bc20 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20   and returns an 
2bc30 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  error..** </li>.
2bc40 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57  **.** <li>.** ^W
2bc50 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
2bc60 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  urs, [sqlite3_st
2bc70 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
2bc80 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
2bc90 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20  ailed.** [error 
2bca0 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
2bcb0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
2bcc0 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62  .  ^The legacy b
2bcd0 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74  ehavior was that
2bce0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2bcf0 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
2bd00 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
2bd10 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2bd20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61  result code.** a
2bd30 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
2bd40 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  on would have to
2bd50 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
2bd60 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2bd70 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f  reset()].** in o
2bd80 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65  rder to find the
2bd90 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
2bda0 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
2bdb0 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
2bdc0 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
2bdd0 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
2bde0 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
2bdf0 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
2be00 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
2be10 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  ly..** </li>.**.
2be20 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
2be30 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
2be40 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61  e bound to [para
2be50 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72  meter | host par
2be60 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a  ameter] in the .
2be70 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ** WHERE clause 
2be80 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
2be90 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75  the choice of qu
2bea0 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73  ery plan for a s
2beb0 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65  tatement,.** the
2bec0 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
2bed0 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
2bee0 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64  cally recompiled
2bef0 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61  , as if there ha
2bf00 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68  d been .** a sch
2bf10 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74  ema change, on t
2bf20 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74  he first  [sqlit
2bf30 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
2bf40 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68  following any ch
2bf50 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ange.** to the [
2bf60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2bf70 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66  t | bindings] of
2bf80 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72   that [parameter
2bf90 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63  ]. .** ^The spec
2bfa0 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48  ific value of WH
2bfb0 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61  ERE-clause [para
2bfc0 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66  meter] might inf
2bfd0 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63  luence the .** c
2bfe0 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
2bff0 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d  lan if the param
2c000 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74  eter is the left
2c010 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20  -hand side of a 
2c020 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c  [LIKE].** or [GL
2c030 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20  OB] operator or 
2c040 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
2c050 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20   is compared to 
2c060 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d  an indexed colum
2c070 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51  n.** and the [SQ
2c080 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54  LITE_ENABLE_STAT
2c090 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  3] compile-time 
2c0a0 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
2c0b0 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  d..** </li>.** <
2c0c0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e 5e 73  /ol>.**.** <p>^s
2c0d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2c0e0 33 28 29 20 64 69 66 66 65 72 73 20 66 72 6f 6d  3() differs from
2c0f0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2c100 5f 76 32 28 29 20 6f 6e 6c 79 20 69 6e 20 68 61  _v2() only in ha
2c110 76 69 6e 67 0a 2a 2a 20 74 68 65 20 65 78 74 72  ving.** the extr
2c120 61 20 70 72 65 70 46 6c 61 67 73 20 70 61 72 61  a prepFlags para
2c130 6d 65 74 65 72 2c 20 77 68 69 63 68 20 69 73 20  meter, which is 
2c140 61 20 62 69 74 20 61 72 72 61 79 20 63 6f 6e 73  a bit array cons
2c150 69 73 74 69 6e 67 20 6f 66 20 7a 65 72 6f 20 6f  isting of zero o
2c160 72 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65  r.** more of the
2c170 20 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45   [SQLITE_PREPARE
2c180 5f 50 45 52 53 49 53 54 45 4e 54 7c 53 51 4c 49  _PERSISTENT|SQLI
2c190 54 45 5f 50 52 45 50 41 52 45 5f 2a 5d 20 66 6c  TE_PREPARE_*] fl
2c1a0 61 67 73 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ags.  ^The.** sq
2c1b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2c1c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
2c1d0 6b 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  ks exactly the s
2c1e0 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65  ame as.** sqlite
2c1f0 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 20 77  3_prepare_v3() w
2c200 69 74 68 20 61 20 7a 65 72 6f 20 70 72 65 70 46  ith a zero prepF
2c210 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 2e 0a  lags parameter..
2c220 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
2c230 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
2c240 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2c250 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2c260 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2c270 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
2c280 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2c290 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
2c2a0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2c2b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2c2c0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2c2d0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2c2e0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2c2f0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2c300 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2c310 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2c320 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
2c330 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2c340 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2c350 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2c360 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
2c370 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
2c380 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2c390 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2c3a0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
2c3b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
2c3c0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
2c3d0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
2c3e0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2c3f0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2c400 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2c410 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2c420 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2c430 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2c440 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2c450 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2c460 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2c470 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2c480 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2c490 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2c4a0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
2c4b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2c4c0 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v3(.  sqlite3 *d
2c4d0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2c4e0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2c4f0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2c500 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2c510 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2c520 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
2c530 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2c540 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2c550 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2c560 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2c570 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  /.  unsigned int
2c580 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a   prepFlags, /* Z
2c590 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49  ero or more SQLI
2c5a0 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c 61 67  TE_PREPARE_ flag
2c5b0 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  s */.  sqlite3_s
2c5c0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2c5d0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2c5e0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2c5f0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
2c600 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2c610 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2c620 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2c630 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2c640 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
2c650 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2c660 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2c670 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2c680 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
2c690 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2c6a0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
2c6b0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2c6c0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2c6d0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2c6e0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2c6f0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2c700 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2c710 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2c720 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2c730 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
2c740 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2c750 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2c760 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2c770 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
2c780 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2c790 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
2c7a0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2c7b0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2c7c0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2c7d0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
2c7e0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2c7f0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2c800 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2c810 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2c820 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2c830 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2c840 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2c850 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2c860 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2c870 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2c880 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
2c890 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2c8a0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2c8b0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2c8c0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2c8d0 70 72 65 70 61 72 65 31 36 5f 76 33 28 0a 20 20  prepare16_v3(.  
2c8e0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2c8f0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2c900 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
2c910 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
2c920 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
2c930 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
2c940 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2c950 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2c960 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2c970 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2c980 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75  in bytes. */.  u
2c990 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65 70  nsigned int prep
2c9a0 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f  Flags, /* Zero o
2c9b0 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50 52  r more SQLITE_PR
2c9c0 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a  EPARE_ flags */.
2c9d0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2c9e0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2c9f0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2ca00 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2ca10 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
2ca20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2ca30 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2ca40 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2ca50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ca60 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
2ca70 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54  ement SQL.** MET
2ca80 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2ca90 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2caa0 69 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 65  ite3_sql(P) inte
2cab0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2cac0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 70  pointer to a cop
2cad0 79 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a 2a  y of the UTF-8.*
2cae0 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
2caf0 74 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70 61  to create [prepa
2cb00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
2cb10 20 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 65   if P was.** cre
2cb20 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ated by [sqlite3
2cb30 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2cb40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2cb50 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v3()],.** [sqli
2cb60 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2cb70 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
2cb80 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
2cb90 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2cba0 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50  3_expanded_sql(P
2cbb0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2cbc0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2cbd0 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69   a UTF-8.** stri
2cbe0 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
2cbf0 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70 72  e SQL text of pr
2cc00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2cc10 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e   P with.** [boun
2cc20 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65 78  d parameters] ex
2cc30 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  panded..**.** ^(
2cc40 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
2cc50 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
2cc60 6d 65 6e 74 20 69 73 20 63 72 65 61 74 65 64 20  ment is created 
2cc70 75 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a  using the SQL.**
2cc80 20 74 65 78 74 20 22 53 45 4c 45 43 54 20 24 61   text "SELECT $a
2cc90 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66 20  bc,:xyz" and if 
2cca0 70 61 72 61 6d 65 74 65 72 20 24 61 62 63 20 69  parameter $abc i
2ccb0 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67  s bound to integ
2ccc0 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70  er 2345.** and p
2ccd0 61 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69 73  arameter :xyz is
2cce0 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73   unbound, then s
2ccf0 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69 6c  qlite3_sql() wil
2cd00 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  l return.** the 
2cd10 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c  original string,
2cd20 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78   "SELECT $abc,:x
2cd30 79 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33 5f  yz" but sqlite3_
2cd40 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a  expanded_sql().*
2cd50 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22 53  * will return "S
2cd60 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22  ELECT 2345,NULL"
2cd70 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
2cd80 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2cd90 73 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20  sql() interface 
2cda0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20  returns NULL if 
2cdb0 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  insufficient mem
2cdc0 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61  ory.** is availa
2cdd0 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ble to hold the 
2cde0 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74 68  result, or if th
2cdf0 65 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20 65  e result would e
2ce00 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68 65  xceed the.** the
2ce10 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67 20   maximum string 
2ce20 6c 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e 65  length determine
2ce30 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  d by the [SQLITE
2ce40 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a  _LIMIT_LENGTH]..
2ce50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
2ce60 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49  TE_TRACE_SIZE_LI
2ce70 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  MIT] compile-tim
2ce80 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20  e option limits 
2ce90 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62  the size of.** b
2cea0 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20 65  ound parameter e
2ceb0 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65  xpansions.  ^The
2cec0 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52   [SQLITE_OMIT_TR
2ced0 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
2cee0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73  e.** option caus
2cef0 65 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  es sqlite3_expan
2cf00 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77  ded_sql() to alw
2cf10 61 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e  ays return NULL.
2cf20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69  .**.** ^The stri
2cf30 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ng returned by s
2cf40 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 73  qlite3_sql(P) is
2cf50 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c 69   managed by SQLi
2cf60 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75 74  te and is.** aut
2cf70 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64  omatically freed
2cf80 20 77 68 65 6e 20 74 68 65 20 70 72 65 70 61 72   when the prepar
2cf90 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ed statement is 
2cfa0 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54  finalized..** ^T
2cfb0 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e  he string return
2cfc0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65 78  ed by sqlite3_ex
2cfd0 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f  panded_sql(P), o
2cfe0 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64  n the other hand
2cff0 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 64  ,.** is obtained
2d000 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2d010 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73  alloc()] and mus
2d020 74 20 62 65 20 66 72 65 65 20 62 79 20 74 68 65  t be free by the
2d030 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
2d040 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  by passing it to
2d050 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
2d060 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
2d070 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71   *sqlite3_sql(sq
2d080 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2d090 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
2d0a0 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73  3_expanded_sql(s
2d0b0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2d0c0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2d0d0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
2d0e0 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
2d0f0 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44  ent Writes The D
2d100 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f  atabase.** METHO
2d110 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2d120 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2d130 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2d140 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (X) interface re
2d150 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
2d160 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20  zero) if.** and 
2d170 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65  only if the [pre
2d180 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d190 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65   X makes no dire
2d1a0 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a  ct changes to.**
2d1b0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2d1c0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2d1d0 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  e..**.** Note th
2d1e0 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  at [application-
2d1f0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2d200 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69  tions] or.** [vi
2d210 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69  rtual tables] mi
2d220 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  ght change the d
2d230 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74  atabase indirect
2d240 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66  ly as a side eff
2d250 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20  ect.  .** ^(For 
2d260 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61  example, if an a
2d270 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2d280 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65  es a function "e
2d290 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20  val()" that .** 
2d2a0 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65  calls [sqlite3_e
2d2b0 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  xec()], then the
2d2c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73   following SQL s
2d2d0 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a  tatement would.*
2d2e0 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  * change the dat
2d2f0 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75  abase file throu
2d300 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a  gh side-effects:
2d310 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
2d320 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53  te><pre>.**    S
2d330 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45  ELECT eval('DELE
2d340 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f  TE FROM t1') FRO
2d350 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  M t2;.** </pre><
2d360 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
2d370 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74  ** But because t
2d380 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
2d390 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
2d3a0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
2d3b0 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63  se file.** direc
2d3c0 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  tly, sqlite3_stm
2d3d0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75  t_readonly() wou
2d3e0 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20  ld still return 
2d3f0 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  true.)^.**.** ^T
2d400 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
2d410 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75  ol statements su
2d420 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b  ch as [BEGIN], [
2d430 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41  COMMIT], [ROLLBA
2d440 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49  CK],.** [SAVEPOI
2d450 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53  NT], and [RELEAS
2d460 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33  E] cause sqlite3
2d470 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
2d480 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c   to return true,
2d490 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74  .** since the st
2d4a0 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c  atements themsel
2d4b0 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61  ves do not actua
2d4c0 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64  lly modify the d
2d4d0 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72  atabase but.** r
2d4e0 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72  ather they contr
2d4f0 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66  ol the timing of
2d500 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74   when other stat
2d510 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68  ements modify th
2d520 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  e .** database. 
2d530 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61   ^The [ATTACH] a
2d540 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74  nd [DETACH] stat
2d550 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73  ements also caus
2d560 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  e.** sqlite3_stm
2d570 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
2d580 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63  return true sinc
2d590 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73  e, while those s
2d5a0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61  tatements.** cha
2d5b0 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72  nge the configur
2d5c0 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62  ation of a datab
2d5d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
2d5e0 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65  they do not make
2d5f0 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20   .** changes to 
2d600 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2d610 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2d620 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54  s on disk..** ^T
2d630 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
2d640 72 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72  readonly() inter
2d650 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
2d660 65 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69  e for [BEGIN] si
2d670 6e 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d  nce.** [BEGIN] m
2d680 65 72 65 6c 79 20 73 65 74 73 20 69 6e 74 65 72  erely sets inter
2d690 6e 61 6c 20 66 6c 61 67 73 2c 20 62 75 74 20 74  nal flags, but t
2d6a0 68 65 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20  he [BEGIN|BEGIN 
2d6b0 49 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a  IMMEDIATE] and.*
2d6c0 2a 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 45  * [BEGIN|BEGIN E
2d6d0 58 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e  XCLUSIVE] comman
2d6e0 64 73 20 64 6f 20 74 6f 75 63 68 20 74 68 65 20  ds do touch the 
2d6f0 64 61 74 61 62 61 73 65 20 61 6e 64 20 73 6f 0a  database and so.
2d700 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
2d710 72 65 61 64 6f 6e 6c 79 28 29 20 72 65 74 75 72  readonly() retur
2d720 6e 73 20 66 61 6c 73 65 20 66 6f 72 20 74 68 6f  ns false for tho
2d730 73 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a  se commands..*/.
2d740 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
2d750 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65  _readonly(sqlite
2d760 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2d770 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d780 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20   Determine If A 
2d790 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2d7a0 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65  nt Has Been Rese
2d7b0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2d7c0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2d7d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
2d7e0 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66  t_busy(S) interf
2d7f0 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
2d800 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74   (non-zero) if t
2d810 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2d820 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73  statement] S has
2d830 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74   been stepped at
2d840 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e   least once usin
2d850 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  g .** [sqlite3_s
2d860 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20  tep(S)] but has 
2d870 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63  neither run to c
2d880 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72  ompletion (retur
2d890 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  ned.** [SQLITE_D
2d8a0 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ONE] from [sqlit
2d8b0 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72  e3_step(S)]) nor
2d8c0 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75  .** been reset u
2d8d0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
2d8e0 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73  set(S)].  ^The s
2d8f0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
2d900 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  (S).** interface
2d910 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69   returns false i
2d920 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f S is a NULL po
2d930 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20  inter.  If S is 
2d940 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70  not a .** NULL p
2d950 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f  ointer and is no
2d960 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  t a pointer to a
2d970 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64   valid [prepared
2d980 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
2d990 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20  bject, then the 
2d9a0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
2d9b0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
2d9c0 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ly undesirable..
2d9d0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
2d9e0 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
2d9f0 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20   in combination 
2da00 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
2da10 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61  mt()].** to loca
2da20 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20  te all prepared 
2da30 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63  statements assoc
2da40 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74  iated with a dat
2da50 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63  abase .** connec
2da60 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e  tion that are in
2da70 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72   need of being r
2da80 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20  eset.  This can 
2da90 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20  be used,.** for 
2daa0 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67  example, in diag
2dab0 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20  nostic routines 
2dac0 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72  to search for pr
2dad0 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65  epared .** state
2dae0 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68  ments that are h
2daf0 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63  olding a transac
2db00 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e  tion open..*/.in
2db10 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  t sqlite3_stmt_b
2db20 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  usy(sqlite3_stmt
2db30 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2db40 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79  REF: Dynamically
2db50 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
2db60 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
2db70 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
2db80 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
2db90 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2dba0 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
2dbb0 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
2dbc0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2dbd0 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
2dbe0 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
2dbf0 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
2dc00 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
2dc10 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
2dc20 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
2dc30 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
2dc40 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56  s it stores.  ^V
2dc50 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
2dc60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2dc70 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20  jects.** can be 
2dc80 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
2dc90 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
2dca0 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
2dcb0 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
2dcc0 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
2dcd0 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
2dce0 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
2dcf0 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
2dd00 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
2dd10 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
2dd20 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
2dd30 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
2dd40 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
2dd50 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
2dd60 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
2dd70 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
2dd80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
2dd90 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
2dda0 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
2ddb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
2ddc0 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
2ddd0 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e  .** whether or n
2dde0 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61  ot it requires a
2ddf0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
2de00 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a  e3_value.  The.*
2de10 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
2de20 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63  _dup()] interfac
2de30 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
2de40 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77   construct a new
2de50 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73   .** protected s
2de60 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f  qlite3_value fro
2de70 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  m an unprotected
2de80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
2de90 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20  **.** The terms 
2dea0 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20  "protected" and 
2deb0 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65  "unprotected" re
2dec0 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f  fer to whether o
2ded0 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78  r not.** a mutex
2dee0 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e   is held.  An in
2def0 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20  ternal mutex is 
2df00 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65  held for a prote
2df10 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
2df20 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74  value object but
2df30 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c   no mutex is hel
2df40 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  d for an unprote
2df50 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
2df60 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49  value object.  I
2df70 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2df80 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c  iled to be singl
2df90 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77  e-threaded.** (w
2dfa0 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  ith [SQLITE_THRE
2dfb0 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69  ADSAFE=0] and wi
2dfc0 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  th [sqlite3_thre
2dfd0 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e  adsafe()] return
2dfe0 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20  ing 0).** or if 
2dff0 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e  SQLite is run in
2e000 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20   one of reduced 
2e010 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20  mutex modes .** 
2e020 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
2e030 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20  INGLETHREAD] or 
2e040 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2e050 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74  ULTITHREAD].** t
2e060 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20  hen there is no 
2e070 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
2e080 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
2e090 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
2e0a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2e0b0 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20  bjects and they 
2e0c0 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65  can be used inte
2e0d0 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f  rchangeably.  Ho
2e0e0 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61  wever,.** for ma
2e0f0 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61  ximum code porta
2e100 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63  bility it is rec
2e110 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
2e120 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74  plications.** st
2e130 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73  ill make the dis
2e140 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
2e150 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
2e160 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
2e170 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2e180 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f  cts even when no
2e190 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69  t strictly requi
2e1a0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  red..**.** ^The 
2e1b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2e1c0 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70  jects that are p
2e1d0 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74  assed as paramet
2e1e0 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ers into the.** 
2e1f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2e200 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  f [application-d
2e210 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2e220 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63  ions] are protec
2e230 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ted..** ^The sql
2e240 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2e250 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2e260 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2e270 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70  _value()] is unp
2e280 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70  rotected..** Unp
2e290 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2e2a0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d  _value objects m
2e2b0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
2e2c0 61 73 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  as arguments.** 
2e2d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
2e2e0 6c 74 5f 76 61 6c 75 65 28 29 5d 2c 20 5b 73 71  lt_value()], [sq
2e2f0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
2e300 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2e310 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29  ite3_value_dup()
2e320 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
2e330 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20  e3_value_blob | 
2e340 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
2e350 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  pe()] family of.
2e360 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  ** interfaces re
2e370 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20  quire protected 
2e380 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2e390 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  jects..*/.typede
2e3a0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
2e3b0 5f 76 61 6c 75 65 20 73 71 6c 69 74 65 33 5f 76  _value sqlite3_v
2e3c0 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  alue;../*.** CAP
2e3d0 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74  I3REF: SQL Funct
2e3e0 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65  ion Context Obje
2e3f0 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e  ct.**.** The con
2e400 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e  text in which an
2e410 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78   SQL function ex
2e420 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64  ecutes is stored
2e430 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   in an.** sqlite
2e440 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
2e450 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f  .  ^A pointer to
2e460 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74   an sqlite3_cont
2e470 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73  ext object.** is
2e480 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61   always first pa
2e490 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c  rameter to [appl
2e4a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2e4b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  SQL functions]..
2e4c0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
2e4d0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2e4e0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2e4f0 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73  tation will pass
2e500 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72   this.** pointer
2e510 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61   through into ca
2e520 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2e530 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c  result_int | sql
2e540 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a  ite3_result()],.
2e550 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  ** [sqlite3_aggr
2e560 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d  egate_context()]
2e570 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  , [sqlite3_user_
2e580 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  data()],.** [sql
2e590 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
2e5a0 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69  handle()], [sqli
2e5b0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
2e5c0 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73  )],.** and/or [s
2e5d0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2e5e0 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  ta()]..*/.typede
2e5f0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
2e600 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33  _context sqlite3
2e610 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a  _context;../*.**
2e620 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69   CAPI3REF: Bindi
2e630 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
2e640 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
2e650 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68  .** KEYWORDS: {h
2e660 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  ost parameter} {
2e670 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d  host parameters}
2e680 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
2e690 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52   name}.** KEYWOR
2e6a0 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  DS: {SQL paramet
2e6b0 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  er} {SQL paramet
2e6c0 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20  ers} {parameter 
2e6d0 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48  binding}.** METH
2e6e0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2e6f0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20  .**.** ^(In the 
2e700 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
2e710 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  xt input to [sql
2e720 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2e730 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  )] and its varia
2e740 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73  nts,.** literals
2e750 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64   may be replaced
2e760 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72   by a [parameter
2e770 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f  ] that matches o
2e780 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a  ne of following.
2e790 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a  ** templates:.**
2e7a0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
2e7b0 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e    ?.** <li>  ?NN
2e7c0 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a  N.** <li>  :VVV.
2e7d0 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a  ** <li>  @VVV.**
2e7e0 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c   <li>  $VVV.** <
2e7f0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  /ul>.**.** In th
2e800 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76  e templates abov
2e810 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74  e, NNN represent
2e820 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74  s an integer lit
2e830 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56  eral,.** and VVV
2e840 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61   represents an a
2e850 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e  lphanumeric iden
2e860 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20  tifier.)^  ^The 
2e870 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a  values of these.
2e880 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  ** parameters (a
2e890 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
2e8a0 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
2e8b0 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  " or "SQL parame
2e8c0 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
2e8d0 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
2e8e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2e8f0 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
2e900 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   here..**.** ^Th
2e910 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2e920 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2e930 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2e940 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61  s is always.** a
2e950 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2e960 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
2e970 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66  bject returned f
2e980 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
2e990 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2e9a0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a   its variants..*
2e9b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
2e9c0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
2e9d0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51   index of the SQ
2e9e0 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  L parameter to b
2e9f0 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  e set..** ^The l
2ea00 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
2ea10 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
2ea20 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20  ex of 1.  ^When 
2ea30 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a  the same named.*
2ea40 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
2ea50 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
2ea60 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61  n once, second a
2ea70 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  nd subsequent.**
2ea80 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76   occurrences hav
2ea90 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78  e the same index
2eaa0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   as the first oc
2eab0 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68  currence..** ^Th
2eac0 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65  e index for name
2ead0 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e  d parameters can
2eae0 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73   be looked up us
2eaf0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
2eb00 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2eb10 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20  er_index()] API 
2eb20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68  if desired.  ^Th
2eb30 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
2eb40 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
2eb50 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
2eb60 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e   NNN..** ^The NN
2eb70 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20  N value must be 
2eb80 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68  between 1 and th
2eb90 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  e [sqlite3_limit
2eba0 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ()].** parameter
2ebb0 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56   [SQLITE_LIMIT_V
2ebc0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20  ARIABLE_NUMBER] 
2ebd0 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20  (default value: 
2ebe0 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  999)..**.** ^The
2ebf0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
2ec00 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  is the value to 
2ec10 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61  bind to the para
2ec20 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  meter..** ^If th
2ec30 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2ec40 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2ec50 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
2ec60 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2ec70 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2ec80 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61  bind_blob() is a
2ec90 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
2eca0 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  en the fourth pa
2ecb0 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67  rameter.** is ig
2ecc0 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e  nored and the en
2ecd0 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20  d result is the 
2ece0 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f  same as sqlite3_
2ecf0 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a  bind_null()..**.
2ed00 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f  ** ^(In those ro
2ed10 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
2ed20 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
2ed30 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
2ed40 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
2ed50 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
2ed60 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
2ed70 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
2ed80 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
2ed90 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
2eda0 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
2edb0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
2edc0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e  of characters.)^
2edd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72  .** ^If the four
2ede0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2edf0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2ee00 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
2ee10 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
2ee20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2ee30 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  n the length of 
2ee40 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
2ee50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2ee60 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
2ee70 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
2ee80 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ator..** If the 
2ee90 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2eea0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2eeb0 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74  _blob() is negat
2eec0 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ive, then.** the
2eed0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2eee0 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20  efined..** If a 
2eef0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75  non-negative fou
2ef00 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
2ef10 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c   provided to sql
2ef20 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
2ef30 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
2ef40 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20  ind_text16() or 
2ef50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2ef60 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68  t64() then.** th
2ef70 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  at parameter mus
2ef80 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
2ef90 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68  fset.** where th
2efa0 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
2efb0 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73   would occur ass
2efc0 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67  uming the string
2efd0 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72   were NUL.** ter
2efe0 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
2eff0 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
2f000 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66  occur at byte of
2f010 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20  fsets less than 
2f020 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66  .** the value of
2f030 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2f040 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72  meter then the r
2f050 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
2f060 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f  value will.** co
2f070 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e  ntain embedded N
2f080 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ULs.  The result
2f090 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
2f0a0 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67  involving string
2f0b0 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64  s.** with embedd
2f0c0 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
2f0d0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2f0e0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2f0f0 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20  to the BLOB and 
2f100 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69  string binding i
2f110 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
2f120 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65  a destructor use
2f130 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  d to dispose of 
2f140 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73  the BLOB or.** s
2f150 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69  tring after SQLi
2f160 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
2f170 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64  with it.  ^The d
2f180 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
2f190 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73  led.** to dispos
2f1a0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
2f1b0 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20   string even if 
2f1c0 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64  the call to bind
2f1d0 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e   API fails..** ^
2f1e0 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
2f1f0 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20  ument is.** the 
2f200 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
2f210 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
2f220 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
2f230 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69  es that the.** i
2f240 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e  nformation is in
2f250 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
2f260 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
2f270 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
2f280 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74   freed..** ^If t
2f290 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2f2a0 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20  t has the value 
2f2b0 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
2f2c0 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  T], then.** SQLi
2f2d0 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e  te makes its own
2f2e0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
2f2f0 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69   the data immedi
2f300 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a  ately, before.**
2f310 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2f320 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65  d_*() routine re
2f330 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  turns..**.** ^Th
2f340 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74  e sixth argument
2f350 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2f360 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20 62  _text64() must b
2f370 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c  e one of.** [SQL
2f380 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
2f390 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49  TE_UTF16], [SQLI
2f3a0 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20  TE_UTF16BE], or 
2f3b0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
2f3c0 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74  .** to specify t
2f3d0 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74  he encoding of t
2f3e0 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20 74  he text in the t
2f3f0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20  hird parameter. 
2f400 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68   If.** the sixth
2f410 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
2f420 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2f430 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
2f440 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20   the.** allowed 
2f450 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f  values shown abo
2f460 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65  ve, or if the te
2f470 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  xt encoding is d
2f480 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d  ifferent.** from
2f490 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70   the encoding sp
2f4a0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 73  ecified by the s
2f4b0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  ixth parameter, 
2f4c0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2f4d0 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  r.** is undefine
2f4e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2f4f0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
2f500 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
2f510 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
2f520 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
2f530 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
2f540 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c  roes.  ^A zerobl
2f550 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
2f560 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
2f570 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
2f580 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73  eger to hold its
2f590 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
2f5a0 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
2f5b0 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
2f5c0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
2f5d0 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68   serve as placeh
2f5e0 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
2f5f0 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
2f600 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
2f610 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  en using.** [sql
2f620 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
2f630 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
2f640 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
2f650 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20  .** ^A negative 
2f660 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
2f670 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
2f680 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
2f690 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  BLOB..**.** ^The
2f6a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f   sqlite3_bind_po
2f6b0 69 6e 74 65 72 28 53 2c 49 2c 50 2c 54 2c 44 29  inter(S,I,P,T,D)
2f6c0 20 72 6f 75 74 69 6e 65 20 63 61 75 73 65 73 20   routine causes 
2f6d0 74 68 65 20 49 2d 74 68 20 70 61 72 61 6d 65 74  the I-th paramet
2f6e0 65 72 20 69 6e 0a 2a 2a 20 5b 70 72 65 70 61 72  er in.** [prepar
2f6f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2f700 74 6f 20 68 61 76 65 20 61 6e 20 53 51 4c 20 76  to have an SQL v
2f710 61 6c 75 65 20 6f 66 20 4e 55 4c 4c 2c 20 62 75  alue of NULL, bu
2f720 74 20 74 6f 20 61 6c 73 6f 20 62 65 0a 2a 2a 20  t to also be.** 
2f730 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2f740 74 68 65 20 70 6f 69 6e 74 65 72 20 50 20 6f 66  the pointer P of
2f750 20 74 79 70 65 20 54 2e 20 20 5e 44 20 69 73 20   type T.  ^D is 
2f760 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
2f770 69 6e 74 65 72 20 6f 72 0a 2a 2a 20 61 20 70 6f  inter or.** a po
2f780 69 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74 72  inter to a destr
2f790 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 66  uctor function f
2f7a0 6f 72 20 50 2e 20 5e 53 51 4c 69 74 65 20 77 69  or P. ^SQLite wi
2f7b0 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 0a 2a 2a  ll invoke the.**
2f7c0 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69   destructor D wi
2f7d0 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  th a single argu
2f7e0 6d 65 6e 74 20 6f 66 20 50 20 77 68 65 6e 20 69  ment of P when i
2f7f0 74 20 69 73 20 66 69 6e 69 73 68 65 64 20 75 73  t is finished us
2f800 69 6e 67 0a 2a 2a 20 50 2e 20 20 54 68 65 20 54  ing.** P.  The T
2f810 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c   parameter shoul
2f820 64 20 62 65 20 61 20 73 74 61 74 69 63 20 73 74  d be a static st
2f830 72 69 6e 67 2c 20 70 72 65 66 65 72 61 62 6c 79  ring, preferably
2f840 20 61 20 73 74 72 69 6e 67 0a 2a 2a 20 6c 69 74   a string.** lit
2f850 65 72 61 6c 2e 20 54 68 65 20 73 71 6c 69 74 65  eral. The sqlite
2f860 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 29  3_bind_pointer()
2f870 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 72 74   routine is part
2f880 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 6f 69 6e   of the.** [poin
2f890 74 65 72 20 70 61 73 73 69 6e 67 20 69 6e 74 65  ter passing inte
2f8a0 72 66 61 63 65 5d 20 61 64 64 65 64 20 66 6f 72  rface] added for
2f8b0 20 53 51 4c 69 74 65 20 33 2e 32 30 2e 30 2e 0a   SQLite 3.20.0..
2f8c0 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66  **.** ^If any of
2f8d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2f8e0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61  d_*() routines a
2f8f0 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  re called with a
2f900 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
2f910 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
2f920 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72  ed statement] or
2f930 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64   with a prepared
2f940 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77   statement for w
2f950 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hich.** [sqlite3
2f960 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65  _step()] has bee
2f970 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65  n called more re
2f980 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c  cently than [sql
2f990 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a  ite3_reset()],.*
2f9a0 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20  * then the call 
2f9b0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
2f9c0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66  ITE_MISUSE].  If
2f9d0 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e   any sqlite3_bin
2f9e0 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  d_().** routine 
2f9f0 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65  is passed a [pre
2fa00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2fa10 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66   that has been f
2fa20 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a  inalized, the.**
2fa30 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
2fa40 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
2fa50 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
2fa60 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e   ^Bindings are n
2fa70 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
2fa80 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
2fa90 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
2faa0 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ^Unbound paramet
2fab0 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  ers are interpre
2fac0 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ted as NULL..**.
2fad0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2fae0 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20  bind_* routines 
2faf0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
2fb00 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
2fb10 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
2fb20 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20  de] if anything 
2fb30 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e  goes wrong..** ^
2fb40 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20  [SQLITE_TOOBIG] 
2fb50 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
2fb60 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66  d if the size of
2fb70 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
2fb80 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d  B.** exceeds lim
2fb90 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b  its imposed by [
2fba0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
2fbb0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
2fbc0 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c  GTH]) or.** [SQL
2fbd0 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e  ITE_MAX_LENGTH].
2fbe0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e  .** ^[SQLITE_RAN
2fbf0 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
2fc00 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
2fc10 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
2fc20 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51   of range.  ^[SQ
2fc30 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72  LITE_NOMEM] is r
2fc40 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f  eturned if mallo
2fc50 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  c() fails..**.**
2fc60 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2fc70 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2fc80 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20  er_count()],.** 
2fc90 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2fca0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
2fcb0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
2fcc0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2fcd0 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
2fce0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2fcf0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2fd00 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
2fd10 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
2fd20 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
2fd30 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34  ite3_bind_blob64
2fd40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2fd50 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2fd60 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
2fd70 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2fd80 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a            void(*
2fd90 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
2fda0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
2fdb0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
2fdc0 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
2fdd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2fde0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
2fdf0 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
2fe00 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2fe10 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
2fe20 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
2fe30 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
2fe40 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
2fe50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2fe60 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
2fe70 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
2fe80 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e  e3_stmt*,int,con
2fe90 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69  st char*,int,voi
2fea0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
2feb0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
2fec0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
2fed0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2fee0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
2fef0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2ff00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2ff10 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt64(sqlite3_stm
2ff20 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
2ff30 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  har*, sqlite3_ui
2ff40 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
2ff50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
2ff60 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75  oid(*)(void*), u
2ff70 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63  nsigned char enc
2ff80 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69  oding);.int sqli
2ff90 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
2ffa0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2ffb0 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
2ffc0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2ffd0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74  lite3_bind_point
2ffe0 65 72 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  er(sqlite3_stmt*
2fff0 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 63 6f  , int, void*, co
30000 6e 73 74 20 63 68 61 72 2a 2c 76 6f 69 64 28 2a  nst char*,void(*
30010 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
30020 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
30030 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
30040 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b  t*, int, int n);
30050 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
30060 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c  d_zeroblob64(sql
30070 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
30080 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29   sqlite3_uint64)
30090 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
300a0 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
300b0 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d   Parameters.** M
300c0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
300d0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  tmt.**.** ^This 
300e0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
300f0 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
30100 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
30110 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
30120 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
30130 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
30140 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
30150 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
30160 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
30170 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
30180 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
30190 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
301a0 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
301b0 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
301c0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
301d0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
301e0 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
301f0 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
30200 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
30210 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75  ne actually retu
30220 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66  rns the index of
30230 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69   the largest (ri
30240 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61  ghtmost).** para
30250 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66  meter. For all f
30260 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e  orms except ?NNN
30270 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72  , this will corr
30280 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a  espond to the.**
30290 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75   number of uniqu
302a0 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49  e parameters.  I
302b0 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  f parameters of 
302c0 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72  the ?NNN form ar
302d0 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
302e0 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
302f0 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a  the list.)^.**.*
30300 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
30310 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
30320 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
30330 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
30340 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
30350 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
30360 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
30370 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
30380 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
30390 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
303a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
303b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
303c0 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
303d0 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45   Parameter.** ME
303e0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
303f0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
30400 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
30410 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69  eter_name(P,N) i
30420 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
30430 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
30440 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61  the N-th [SQL pa
30450 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
30460 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30470 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c  ent] P..** ^(SQL
30480 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
30490 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f  he form "?NNN" o
304a0 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
304b0 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
304c0 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63  have a name whic
304d0 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
304e0 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
304f0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
30500 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69  AAA".** respecti
30510 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65  vely..** In othe
30520 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
30530 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
30540 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a  or "@" or "?".**
30550 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
30560 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
30570 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65  .)^.** ^Paramete
30580 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
30590 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
305a0 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
305b0 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
305c0 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20  nd are referred 
305d0 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22  to as "nameless"
305e0 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   or "anonymous p
305f0 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
30600 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73  * ^The first hos
30610 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
30620 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
30630 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ot 0..**.** ^If 
30640 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f  the value N is o
30650 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
30660 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d  f the N-th param
30670 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
30680 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
30690 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68  s returned.  ^Th
306a0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
306b0 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
306c0 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
306d0 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
306e0 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
306f0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
30700 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
30710 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
30720 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20  repare16()],.** 
30730 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
30740 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b 73 71  16_v2()], or [sq
30750 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
30760 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v3()]..**.** See
30770 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
30780 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
30790 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
307a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
307b0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
307c0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
307d0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
307e0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ndex()]..*/.cons
307f0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
30800 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
30810 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
30820 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
30830 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
30840 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
30850 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
30860 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
30870 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
30880 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
30890 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
308a0 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
308b0 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e  ame.  ^The.** in
308c0 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e  dex value return
308d0 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66  ed is suitable f
308e0 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65  or use as the se
308f0 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  cond.** paramete
30900 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  r to [sqlite3_bi
30910 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
30920 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72  bind()].  ^A zer
30930 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  o.** is returned
30940 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20   if no matching 
30950 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75  parameter is fou
30960 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65  nd.  ^The parame
30970 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
30980 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
30990 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
309a0 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
309b0 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
309c0 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
309d0 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
309e0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
309f0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
30a00 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
30a10 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
30a20 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
30a30 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
30a40 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
30a50 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
30a60 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
30a70 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
30a80 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
30a90 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
30aa0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
30ab0 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73  _index(sqlite3_s
30ac0 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  tmt*, const char
30ad0 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a   *zName);../*.**
30ae0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
30af0 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e   All Bindings On
30b00 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
30b10 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ement.** METHOD:
30b20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
30b30 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f  .** ^Contrary to
30b40 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
30b50 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
30b60 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
30b70 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
30b80 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
30b90 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
30ba0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
30bb0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73  atement]..** ^Us
30bc0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
30bd0 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
30be0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
30bf0 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
30c00 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
30c10 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
30c20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30c30 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
30c40 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
30c50 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t Set.** METHOD:
30c60 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
30c70 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
30c80 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
30c90 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
30ca0 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
30cb0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
30cc0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 49 66   statement]. ^If
30cd0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
30ce0 74 75 72 6e 73 20 30 2c 20 74 68 61 74 20 6d 65  turns 0, that me
30cf0 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65  ans the .** [pre
30d00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
30d10 20 72 65 74 75 72 6e 73 20 6e 6f 20 64 61 74 61   returns no data
30d20 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
30d30 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e   [UPDATE])..** ^
30d40 48 6f 77 65 76 65 72 2c 20 6a 75 73 74 20 62 65  However, just be
30d50 63 61 75 73 65 20 74 68 69 73 20 72 6f 75 74 69  cause this routi
30d60 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73  ne returns a pos
30d70 69 74 69 76 65 20 6e 75 6d 62 65 72 20 64 6f 65  itive number doe
30d80 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74 68  s not.** mean th
30d90 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 72  at one or more r
30da0 6f 77 73 20 6f 66 20 64 61 74 61 20 77 69 6c 6c  ows of data will
30db0 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   be returned.  ^
30dc0 41 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  A SELECT stateme
30dd0 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79  nt.** will alway
30de0 73 20 68 61 76 65 20 61 20 70 6f 73 69 74 69 76  s have a positiv
30df0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
30e00 5f 63 6f 75 6e 74 28 29 20 62 75 74 20 64 65 70  _count() but dep
30e10 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a  ending on the.**
30e20 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
30e30 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68  nstraints and th
30e40 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e 74 2c  e table content,
30e50 20 69 74 20 6d 69 67 68 74 20 72 65 74 75 72 6e   it might return
30e60 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20   no rows..**.** 
30e70 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
30e80 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
30e90 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
30ea0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
30eb0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
30ec0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30ed0 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
30ee0 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
30ef0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
30f00 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
30f10 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
30f20 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
30f30 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
30f40 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
30f50 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
30f60 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
30f70 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54  ] statement.  ^T
30f80 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
30f90 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
30fa0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
30fb0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
30fc0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
30fd0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
30fe0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30ff0 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
31000 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
31010 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
31020 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
31030 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  .  ^The first pa
31040 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
31050 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31060 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
31070 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45  ements the [SELE
31080 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e  CT] statement. ^
31090 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
310a0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
310b0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e  olumn number.  ^
310c0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
310d0 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
310e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
310f0 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
31100 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
31110 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
31120 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31130 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
31140 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
31150 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
31160 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
31170 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
31180 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
31190 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
311a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
311b0 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
311c0 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
311d0 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
311e0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
311f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
31200 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
31210 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
31220 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
31230 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  .**.** ^If sqlit
31240 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
31250 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
31260 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
31270 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
31280 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
31290 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
312a0 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
312b0 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
312c0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
312d0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
312e0 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
312f0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
31300 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
31310 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
31320 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
31330 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
31340 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
31350 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
31360 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
31370 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
31380 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
31390 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
313a0 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
313b0 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
313c0 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f   the next..*/.co
313d0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
313e0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
313f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
31400 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20   N);.const void 
31410 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
31420 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
31430 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
31440 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
31450 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
31460 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
31470 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
31480 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
31490 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
314a0 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
314b0 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
314c0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
314d0 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c  and.** table col
314e0 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20  umn that is the 
314f0 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74  origin of a part
31500 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f  icular result co
31510 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45  lumn in.** [SELE
31520 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  CT] statement..*
31530 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
31540 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
31550 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
31560 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
31570 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
31580 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74  F-8 or UTF-16 st
31590 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74  ring.  ^The _dat
315a0 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
315b0 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
315c0 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
315d0 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
315e0 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
315f0 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
31600 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
31610 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
31620 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
31630 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
31640 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
31650 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65  til the [prepare
31660 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
31670 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69  destroyed.** usi
31680 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
31690 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
316a0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
316b0 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
316c0 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
316d0 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
316e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
316f0 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
31700 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
31710 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
31720 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
31730 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
31740 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
31750 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  ncoding..**.** ^
31760 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
31770 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
31780 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
31790 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
317a0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
317b0 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
317c0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
317d0 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69  ument to these i
317e0 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b  nterfaces is a [
317f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31800 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66  nt]..** ^These f
31810 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
31820 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
31830 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  t the Nth result
31840 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
31850 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
31860 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
31870 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
31880 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
31890 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  * ^The left-most
318a0 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d   column is colum
318b0 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f  n 0 for these ro
318c0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  utines..**.** ^I
318d0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
318e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
318f0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
31900 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
31910 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
31920 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
31930 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
31940 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
31950 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
31960 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
31970 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
31980 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
31990 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
319a0 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e  error.** occurs.
319b0 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68    ^Otherwise, th
319c0 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  ey return the na
319d0 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
319e0 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
319f0 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e  le,.** or column
31a00 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
31a10 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  lt column was ex
31a20 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
31a30 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c  .** ^As with all
31a40 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
31a50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20  Is, those whose 
31a60 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22  names end with "
31a70 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
31a80 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
31a90 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68  ings and the oth
31aa0 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
31ab0 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a  urn UTF-8..**.**
31ac0 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65   ^These APIs are
31ad0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
31ae0 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
31af0 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
31b00 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
31b10 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
31b20 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
31b30 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a  cessor symbol..*
31b40 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
31b50 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
31b60 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
31b70 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
31b80 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
31b90 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
31ba0 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
31bb0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
31bc0 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
31bd0 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
31be0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  ned..**.** If tw
31bf0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
31c00 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
31c10 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  re.** [sqlite3_c
31c20 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
31c30 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74  ame | column met
31c40 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
31c50 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ].** for the sam
31c60 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
31c70 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c  ement] and resul
31c80 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74  t column.** at t
31c90 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
31ca0 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
31cb0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
31cc0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
31cd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
31ce0 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
31cf0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
31d00 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
31d10 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
31d20 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
31d30 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
31d40 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
31d50 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
31d60 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
31d70 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
31d80 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
31d90 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
31da0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
31db0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
31dc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
31dd0 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
31de0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
31df0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
31e00 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
31e10 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
31e20 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
31e30 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
31e40 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
31e50 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
31e60 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
31e70 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  3_stmt.**.** ^(T
31e80 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
31e90 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
31ea0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
31eb0 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
31ec0 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
31ed0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
31ee0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
31ef0 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
31f00 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
31f10 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
31f20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
31f30 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
31f40 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
31f50 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
31f60 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
31f70 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
31f80 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
31f90 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
31fa0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
31fb0 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
31fc0 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
31fd0 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
31fe0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
31ff0 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
32000 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
32010 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
32020 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
32030 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
32040 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
32050 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
32060 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
32070 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
32080 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
32090 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
320a0 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
320b0 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
320c0 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
320d0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
320e0 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
320f0 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
32100 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
32110 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
32120 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
32130 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
32140 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
32150 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
32160 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
32170 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
32180 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
32190 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
321a0 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
321b0 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
321c0 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
321d0 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
321e0 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
321f0 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
32200 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
32210 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
32220 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
32230 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
32240 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
32250 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
32260 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
32270 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
32280 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
32290 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
322a0 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
322b0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
322c0 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
322d0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
322e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
322f0 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  ltype(sqlite3_st
32300 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
32310 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
32320 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
32330 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
32340 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
32350 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e  REF: Evaluate An
32360 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
32370 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
32380 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74  3_stmt.**.** Aft
32390 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
323a0 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
323b0 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
323c0 67 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73 71 6c  g any of.** [sql
323d0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
323e0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  )], [sqlite3_pre
323f0 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c  pare_v3()], [sql
32400 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
32410 32 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  2()],.** or [sql
32420 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
32430 33 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  3()] or one of t
32440 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
32450 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
32460 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
32470 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
32480 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74  6()], this funct
32490 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63  ion.** must be c
324a0 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
324b0 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
324c0 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
324d0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
324e0 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
324f0 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69  vior of the sqli
32500 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72  te3_step() inter
32510 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f  face depend.** o
32520 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74  n whether the st
32530 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70  atement was prep
32540 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e  ared using the n
32550 65 77 65 72 20 22 76 58 22 20 69 6e 74 65 72 66  ewer "vX" interf
32560 61 63 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  aces.** [sqlite3
32570 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20  _prepare_v3()], 
32580 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
32590 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
325a0 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
325b0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
325c0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
325d0 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
325e0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
325f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
32600 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
32610 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
32620 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
32630 2a 20 6e 65 77 20 22 76 58 22 20 69 6e 74 65 72  * new "vX" inter
32640 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
32650 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
32660 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
32670 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
32680 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
32690 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
326a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
326b0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
326c0 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
326d0 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
326e0 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
326f0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
32700 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
32710 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
32720 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
32730 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
32740 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
32750 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
32760 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
32770 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
32780 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
32790 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
327a0 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
327b0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
327c0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
327d0 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
327e0 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
327f0 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
32800 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
32810 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
32820 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
32830 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
32840 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
32850 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
32860 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
32870 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
32880 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
32890 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
328a0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
328b0 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
328c0 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
328d0 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74  n an.** explicit
328e0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
328f0 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
32900 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
32910 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
32920 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
32930 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
32940 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
32950 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
32960 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
32970 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
32980 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
32990 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
329a0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
329b0 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
329c0 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
329d0 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
329e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
329f0 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
32a00 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
32a10 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
32a20 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
32a30 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
32a40 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
32a50 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
32a60 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
32a70 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
32a80 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
32a90 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
32aa0 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
32ab0 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
32ac0 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
32ad0 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
32ae0 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
32af0 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
32b00 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
32b10 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
32b20 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
32b30 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
32b40 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
32b50 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
32b60 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
32b70 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
32b80 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
32b90 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
32ba0 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
32bb0 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
32bc0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
32bd0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
32be0 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
32bf0 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
32c00 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
32c10 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
32c20 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
32c30 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
32c40 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
32c50 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
32c60 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
32c70 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
32c80 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
32c90 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
32ca0 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
32cb0 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
32cc0 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
32cd0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
32ce0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
32cf0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
32d00 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
32d10 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
32d20 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
32d30 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
32d40 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
32d50 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
32d60 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
32d70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
32d80 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
32d90 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
32da0 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
32db0 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
32dc0 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
32dd0 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
32de0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
32df0 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
32e00 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
32e10 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
32e20 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
32e30 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
32e40 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
32e50 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
32e60 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
32e70 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
32e80 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
32e90 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
32ea0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
32eb0 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
32ec0 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
32ed0 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
32ee0 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
32ef0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
32f00 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
32f10 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
32f20 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
32f30 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  1, a call to.** 
32f40 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
32f50 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61  ] was required a
32f60 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
32f70 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
32f80 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74  thing.** other t
32f90 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
32fa0 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
32fb0 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
32fc0 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
32fd0 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
32fe0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72   to reset the pr
32ff0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33000 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
33010 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75  te3_reset()] wou
33020 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ld result in an 
33030 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
33040 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73  return from.** s
33050 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
33060 42 75 74 20 61 66 74 65 72 20 5b 76 65 72 73 69  But after [versi
33070 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b 64  on 3.6.23.1] ([d
33080 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c  ateof:3.6.23.1],
33090 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
330a0 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c  () began.** call
330b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
330c0 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61  et()] automatica
330d0 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63  lly in this circ
330e0 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a  umstance rather.
330f0 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e  ** than returnin
33100 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  g [SQLITE_MISUSE
33110 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20  ].  This is not 
33120 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d  considered a com
33130 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72  patibility.** br
33140 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20  eak because any 
33150 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74  application that
33160 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61   ever receives a
33170 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  n SQLITE_MISUSE 
33180 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b  error.** is brok
33190 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e  en by definition
331a0 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
331b0 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63  MIT_AUTORESET] c
331c0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
331d0 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  on.** can be use
331e0 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65  d to restore the
331f0 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
33200 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79  ..**.** <b>Goofy
33210 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
33220 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67  :</b> In the leg
33230 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
33240 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
33250 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20  ).** API always 
33260 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69  returns a generi
33270 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53  c error code, [S
33280 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f  QLITE_ERROR], fo
33290 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65  llowing any.** e
332a0 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20  rror other than 
332b0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e  [SQLITE_BUSY] an
332c0 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  d [SQLITE_MISUSE
332d0 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c  ].  You must cal
332e0 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  l.** [sqlite3_re
332f0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
33300 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
33310 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
33320 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70  one of the.** sp
33330 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
33340 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72  des] that better
33350 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
33360 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69  rror..** We admi
33370 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61  t that this is a
33380 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20   goofy design.  
33390 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20  The problem has 
333a0 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69  been fixed.** wi
333b0 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
333c0 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70  rface.  If you p
333d0 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f  repare all of yo
333e0 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ur SQL statement
333f0 73 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  s.** using [sqli
33400 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
33410 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
33420 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 6f  epare_v2()].** o
33430 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
33440 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 5b 73  re16_v2()] or [s
33450 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
33460 5f 76 33 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v3()] instead.*
33470 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
33480 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
33490 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
334a0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
334b0 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
334c0 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
334d0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
334e0 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
334f0 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
33500 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
33510 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
33520 58 22 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  X" interfaces is
33530 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f   recommended..*/
33540 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65  .int sqlite3_ste
33550 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
33560 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33570 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  F: Number of col
33580 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74  umns in a result
33590 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   set.** METHOD: 
335a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
335b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
335c0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e  data_count(P) in
335d0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
335e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
335f0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20  lumns in the.** 
33600 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
33610 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
33620 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
33630 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20  ment] P..** ^If 
33640 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
33650 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61  nt P does not ha
33660 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79  ve results ready
33670 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76   to return.** (v
33680 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ia calls to the 
33690 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
336a0 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f  int | sqlite3_co
336b0 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20  lumn_*()] of.** 
336c0 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e  interfaces) then
336d0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
336e0 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30  unt(P) returns 0
336f0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
33700 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
33710 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74  routine also ret
33720 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61  urns 0 if P is a
33730 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
33740 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
33750 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
33760 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
33770 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
33780 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
33790 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
337a0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  rned [SQLITE_DON
337b0 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  E].  ^The sqlite
337c0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a  3_data_count(P).
337d0 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e  ** will return n
337e0 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69  on-zero if previ
337f0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ous call to [sql
33800 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
33810 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54  turned.** [SQLIT
33820 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69  E_ROW], except i
33830 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68  n the case of th
33840 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d  e [PRAGMA increm
33850 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a  ental_vacuum].**
33860 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73   where it always
33870 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69   returns zero si
33880 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66  nce each step of
33890 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70   that multi-step
338a0 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72  .** pragma retur
338b0 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  ns 0 columns of 
338c0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  data..**.** See 
338d0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63  also: [sqlite3_c
338e0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a  olumn_count()].*
338f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61  /.int sqlite3_da
33900 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  ta_count(sqlite3
33910 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
33920 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33930 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61  Fundamental Data
33940 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  types.** KEYWORD
33950 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
33960 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c  *.** ^(Every val
33970 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
33980 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
33990 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
339a0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
339b0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
339c0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
339d0 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
339e0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
339f0 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
33a00 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
33a10 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
33a20 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
33a30 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
33a40 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
33a50 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
33a60 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
33a70 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
33a80 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
33a90 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
33aa0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
33ab0 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
33ac0 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
33ad0 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
33ae0 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
33af0 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
33b00 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
33b10 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
33b20 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
33b30 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
33b40 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
33b50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33b60 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
33b70 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
33b80 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
33b90 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
33ba0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
33bb0 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
33bc0 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
33bd0 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
33be0 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
33bf0 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
33c00 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
33c10 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
33c20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
33c30 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
33c40 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a  s From A Query.*
33c50 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c  * KEYWORDS: {col
33c60 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
33c70 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ions}.** METHOD:
33c80 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
33c90 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72 79 3a 3c  .** <b>Summary:<
33ca0 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  /b>.** <blockquo
33cb0 74 65 3e 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  te><table border
33cc0 3d 30 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 30  =0 cellpadding=0
33cd0 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d 30 3e 0a   cellspacing=0>.
33ce0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
33cf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
33d00 62 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  b</b><td>&rarr;<
33d10 74 64 3e 42 4c 4f 42 20 72 65 73 75 6c 74 0a 2a  td>BLOB result.*
33d20 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
33d30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
33d40 6c 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  le</b><td>&rarr;
33d50 3c 74 64 3e 52 45 41 4c 20 72 65 73 75 6c 74 0a  <td>REAL result.
33d60 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
33d70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
33d80 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
33d90 64 3e 33 32 2d 62 69 74 20 49 4e 54 45 47 45 52  d>32-bit INTEGER
33da0 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c   result.** <tr><
33db0 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
33dc0 6c 75 6d 6e 5f 69 6e 74 36 34 3c 2f 62 3e 3c 74  lumn_int64</b><t
33dd0 64 3e 26 72 61 72 72 3b 3c 74 64 3e 36 34 2d 62  d>&rarr;<td>64-b
33de0 69 74 20 49 4e 54 45 47 45 52 20 72 65 73 75 6c  it INTEGER resul
33df0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  t.** <tr><td><b>
33e00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
33e10 65 78 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  ext</b><td>&rarr
33e20 3b 3c 74 64 3e 55 54 46 2d 38 20 54 45 58 54 20  ;<td>UTF-8 TEXT 
33e30 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74  result.** <tr><t
33e40 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
33e50 75 6d 6e 5f 74 65 78 74 31 36 3c 2f 62 3e 3c 74  umn_text16</b><t
33e60 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d  d>&rarr;<td>UTF-
33e70 31 36 20 54 45 58 54 20 72 65 73 75 6c 74 0a 2a  16 TEXT result.*
33e80 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
33e90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
33ea0 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  e</b><td>&rarr;<
33eb0 74 64 3e 54 68 65 20 72 65 73 75 6c 74 20 61 73  td>The result as
33ec0 20 61 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   an .** [sqlite3
33ed0 5f 76 61 6c 75 65 7c 75 6e 70 72 6f 74 65 63 74  _value|unprotect
33ee0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
33ef0 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 3c 74 72  ] object..** <tr
33f00 3e 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26  ><td>&nbsp;<td>&
33f10 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 0a  nbsp;<td>&nbsp;.
33f20 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
33f30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
33f40 65 73 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  es</b><td>&rarr;
33f50 3c 74 64 3e 53 69 7a 65 20 6f 66 20 61 20 42 4c  <td>Size of a BL
33f60 4f 42 0a 2a 2a 20 6f 72 20 61 20 55 54 46 2d 38  OB.** or a UTF-8
33f70 20 54 45 58 54 20 72 65 73 75 6c 74 20 69 6e 20   TEXT result in 
33f80 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64  bytes.** <tr><td
33f90 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ><b>sqlite3_colu
33fa0 6d 6e 5f 62 79 74 65 73 31 36 26 6e 62 73 70 3b  mn_bytes16&nbsp;
33fb0 26 6e 62 73 70 3b 3c 2f 62 3e 0a 2a 2a 20 3c 74  &nbsp;</b>.** <t
33fc0 64 3e 26 72 61 72 72 3b 26 6e 62 73 70 3b 26 6e  d>&rarr;&nbsp;&n
33fd0 62 73 70 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20  bsp;<td>Size of 
33fe0 55 54 46 2d 31 36 0a 2a 2a 20 54 45 58 54 20 69  UTF-16.** TEXT i
33ff0 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c  n bytes.** <tr><
34000 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
34010 6c 75 6d 6e 5f 74 79 70 65 3c 2f 62 3e 3c 74 64  lumn_type</b><td
34020 3e 26 72 61 72 72 3b 3c 74 64 3e 44 65 66 61 75  >&rarr;<td>Defau
34030 6c 74 0a 2a 2a 20 64 61 74 61 74 79 70 65 20 6f  lt.** datatype o
34040 66 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20  f the result.** 
34050 3c 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f 63 6b 71  </table></blockq
34060 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 44  uote>.**.** <b>D
34070 65 74 61 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a 0a 2a  etails:</b>.**.*
34080 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
34090 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
340a0 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e  tion about a sin
340b0 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
340c0 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73  e current.** res
340d0 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
340e0 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63  ry.  ^In every c
340f0 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72  ase the first ar
34100 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
34110 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70  ter.** to the [p
34120 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34130 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67  t] that is being
34140 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20   evaluated (the 
34150 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a  [sqlite3_stmt*].
34160 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75  ** that was retu
34170 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  rned from [sqlit
34180 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
34190 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76   or one of its v
341a0 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20  ariants).** and 
341b0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
341c0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
341d0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66   of the column f
341e0 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61  or which informa
341f0 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
34200 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65  e returned. ^The
34210 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
34220 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
34230 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78  et has the index
34240 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62   0..** ^The numb
34250 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
34260 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20   the result can 
34270 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
34280 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
34290 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e  column_count()].
342a0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
342b0 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
342c0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70   not currently p
342d0 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20  oint to a valid 
342e0 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a  row, or if the.*
342f0 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69  * column index i
34300 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
34310 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e  the result is un
34320 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73  defined..** Thes
34330 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f  e routines may o
34340 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
34350 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  en the most rece
34360 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
34370 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
34380 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  as returned [SQL
34390 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69  ITE_ROW] and nei
343a0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
343b0 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73  _reset()] nor [s
343c0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
343d0 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  )] have been cal
343e0 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79  led subsequently
343f0 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74  ..** If any of t
34400 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
34410 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  e called after [
34420 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
34430 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
34440 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  finalize()] or a
34450 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
34460 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
34470 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20  ed.** something 
34480 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
34490 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73  TE_ROW], the res
344a0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
344b0 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  ed..** If [sqlit
344c0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
344d0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
344e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
344f0 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63  lize()].** are c
34500 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66  alled from a dif
34510 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68  ferent thread wh
34520 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  ile any of these
34530 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
34540 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74   pending, then t
34550 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
34560 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
34570 54 68 65 20 66 69 72 73 74 20 73 69 78 20 69 6e  The first six in
34580 74 65 72 66 61 63 65 73 20 28 5f 62 6c 6f 62 2c  terfaces (_blob,
34590 20 5f 64 6f 75 62 6c 65 2c 20 5f 69 6e 74 2c 20   _double, _int, 
345a0 5f 69 6e 74 36 34 2c 20 5f 74 65 78 74 2c 20 61  _int64, _text, a
345b0 6e 64 20 5f 74 65 78 74 31 36 29 0a 2a 2a 20 65  nd _text16).** e
345c0 61 63 68 20 72 65 74 75 72 6e 20 74 68 65 20 76  ach return the v
345d0 61 6c 75 65 20 6f 66 20 61 20 72 65 73 75 6c 74  alue of a result
345e0 20 63 6f 6c 75 6d 6e 20 69 6e 20 61 20 73 70 65   column in a spe
345f0 63 69 66 69 63 20 64 61 74 61 20 66 6f 72 6d 61  cific data forma
34600 74 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 72 65  t.  If.** the re
34610 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  sult column is n
34620 6f 74 20 69 6e 69 74 69 61 6c 6c 79 20 69 6e 20  ot initially in 
34630 74 68 65 20 72 65 71 75 65 73 74 65 64 20 66 6f  the requested fo
34640 72 6d 61 74 20 28 66 6f 72 20 65 78 61 6d 70 6c  rmat (for exampl
34650 65 2c 0a 2a 2a 20 69 66 20 74 68 65 20 71 75 65  e,.** if the que
34660 72 79 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ry returns an in
34670 74 65 67 65 72 20 62 75 74 20 74 68 65 20 73 71  teger but the sq
34680 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
34690 74 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  t() interface.**
346a0 20 69 73 20 75 73 65 64 20 74 6f 20 65 78 74 72   is used to extr
346b0 61 63 74 20 74 68 65 20 76 61 6c 75 65 29 20 74  act the value) t
346c0 68 65 6e 20 61 6e 20 61 75 74 6f 6d 61 74 69 63  hen an automatic
346d0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
346e0 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a   is performed..*
346f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34700 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
34710 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
34720 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
34730 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
34740 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
34750 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
34760 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
34770 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65  lt column.  ^The
34780 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
34790 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
347a0 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
347b0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
347c0 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
347d0 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
347e0 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 0a 2a  [SQLITE_NULL]..*
347f0 2a 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  * The return val
34800 75 65 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  ue of sqlite3_co
34810 6c 75 6d 6e 5f 74 79 70 65 28 29 20 63 61 6e 20  lumn_type() can 
34820 62 65 20 75 73 65 64 20 74 6f 20 64 65 63 69 64  be used to decid
34830 65 20 77 68 69 63 68 0a 2a 2a 20 6f 66 20 74 68  e which.** of th
34840 65 20 66 69 72 73 74 20 73 69 78 20 69 6e 74 65  e first six inte
34850 72 66 61 63 65 20 73 68 6f 75 6c 64 20 62 65 20  rface should be 
34860 75 73 65 64 20 74 6f 20 65 78 74 72 61 63 74 20  used to extract 
34870 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  the column value
34880 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72  ..** The value r
34890 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
348a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
348b0 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
348c0 66 75 6c 20 69 66 20 6e 6f 0a 2a 2a 20 61 75 74  ful if no.** aut
348d0 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e 76  omatic type conv
348e0 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
348f0 75 72 72 65 64 20 66 6f 72 20 74 68 65 20 76 61  urred for the va
34900 6c 75 65 20 69 6e 20 71 75 65 73 74 69 6f 6e 2e  lue in question.
34910 20 20 0a 2a 2a 20 41 66 74 65 72 20 61 20 74 79    .** After a ty
34920 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 20 74  pe conversion, t
34930 68 65 20 72 65 73 75 6c 74 20 6f 66 20 63 61 6c  he result of cal
34940 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ling sqlite3_col
34950 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 69 73  umn_type().** is
34960 20 75 6e 64 65 66 69 6e 65 64 2c 20 74 68 6f 75   undefined, thou
34970 67 68 20 68 61 72 6d 6c 65 73 73 2e 20 20 46 75  gh harmless.  Fu
34980 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
34990 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
349a0 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
349b0 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
349c0 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
349d0 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
349e0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
349f0 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20  * If the result 
34a00 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 61 20 54  is a BLOB or a T
34a10 45 58 54 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  EXT string, then
34a20 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
34a30 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 6f  umn_bytes().** o
34a40 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
34a50 5f 62 79 74 65 73 31 36 28 29 20 69 6e 74 65 72  _bytes16() inter
34a60 66 61 63 65 73 20 63 61 6e 20 62 65 20 75 73 65  faces can be use
34a70 64 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  d to determine t
34a80 68 65 20 73 69 7a 65 0a 2a 2a 20 6f 66 20 74 68  he size.** of th
34a90 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
34aa0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  g..**.** ^If the
34ab0 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
34ac0 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e  B or UTF-8 strin
34ad0 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
34ae0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
34af0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
34b00 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
34b10 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
34b20 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
34b30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
34b40 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73  lt is a UTF-16 s
34b50 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
34b60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
34b70 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
34b80 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
34b90 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  -8 and then retu
34ba0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
34bb0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
34bc0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
34bd0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
34be0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
34bf0 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a  n_bytes() uses.*
34c00 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
34c10 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
34c20 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
34c30 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61  a UTF-8 string a
34c40 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
34c50 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
34c60 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
34c70 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
34c80 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
34c90 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
34ca0 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73  _bytes() returns
34cb0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   zero..**.** ^If
34cc0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
34cd0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20   BLOB or UTF-16 
34ce0 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
34cf0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
34d00 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74  ytes16().** rout
34d10 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
34d20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
34d30 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
34d40 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
34d50 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
34d60 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65  TF-8 string, the
34d70 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
34d80 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65  _bytes16() conve
34d90 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
34da0 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20  g to UTF-16 and 
34db0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
34dc0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
34dd0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
34de0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
34df0 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
34e00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
34e10 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  16() uses.** [sq
34e20 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
34e30 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
34e40 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
34e50 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72  -16 string and r
34e60 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
34e70 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
34e80 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
34e90 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
34ea0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
34eb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
34ec0 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a  es16() returns z
34ed0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ero..**.** ^The 
34ee0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
34ef0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
34f00 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
34f10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
34f20 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64  umn_bytes16()] d
34f30 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68  o not include th
34f40 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
34f50 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  rs at the end.**
34f60 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
34f70 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74   ^For clarity: t
34f80 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
34f90 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
34fa0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
34fb0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
34fc0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
34fd0 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20   are the number 
34fe0 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
34ff0 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74  he string, not t
35000 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
35010 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
35020 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  Strings returned
35030 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
35040 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71  mn_text() and sq
35050 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
35060 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65  t16(),.** even e
35070 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72  mpty strings, ar
35080 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  e always zero-te
35090 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
350a0 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
350b0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
350c0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
350d0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
350e0 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  B is a NULL poin
350f0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61  ter..**.** <b>Wa
35100 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20  rning:</b> ^The 
35110 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
35120 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
35130 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61  mn_value()] is a
35140 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
35150 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
35160 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d   object.  In a m
35170 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e 76  ultithreaded env
35180 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20  ironment,.** an 
35190 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
351a0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
351b0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
351c0 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a  d safely with.**
351d0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
351e0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
351f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
35200 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
35210 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
35220 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
35230 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
35240 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
35250 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
35260 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
35270 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
35280 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
35290 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
352a0 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
352b0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
352c0 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
352d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
352e0 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76  es()], the behav
352f0 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ior is not threa
35300 64 73 61 66 65 2e 0a 2a 2a 20 48 65 6e 63 65 2c  dsafe..** Hence,
35310 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
35320 75 6d 6e 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  umn_value() inte
35330 72 66 61 63 65 0a 2a 2a 20 69 73 20 6e 6f 72 6d  rface.** is norm
35340 61 6c 6c 79 20 6f 6e 6c 79 20 75 73 65 66 75 6c  ally only useful
35350 20 77 69 74 68 69 6e 20 74 68 65 20 69 6d 70 6c   within the impl
35360 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 0a 2a  ementation of .*
35370 2a 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  * [application-d
35380 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
35390 69 6f 6e 73 5d 20 6f 72 20 5b 76 69 72 74 75 61  ions] or [virtua
353a0 6c 20 74 61 62 6c 65 73 5d 2c 20 6e 6f 74 20 77  l tables], not w
353b0 69 74 68 69 6e 0a 2a 2a 20 74 6f 70 2d 6c 65 76  ithin.** top-lev
353c0 65 6c 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  el application c
353d0 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ode..**.** The t
353e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
353f0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e  y attempt to con
35400 76 65 72 74 20 74 68 65 20 64 61 74 61 74 79 70  vert the datatyp
35410 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
35420 0a 2a 2a 20 5e 46 6f 72 20 65 78 61 6d 70 6c 65  .** ^For example
35430 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
35440 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
35450 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
35460 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
35470 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
35480 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
35490 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
354a0 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20  ally to perform 
354b0 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  the.** conversio
354c0 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  n automatically.
354d0 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e    ^(The followin
354e0 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
354f0 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a  the conversions.
35500 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c  ** that are appl
35510 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
35520 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
35530 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
35540 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
35550 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
35560 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
35570 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
35580 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
35590 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
355a0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
355b0 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
355c0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
355d0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
355e0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
355f0 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
35600 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
35610 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
35620 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
35630 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
35640 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
35650 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73  BLOB    <td> Res
35660 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
35670 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
35680 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
35690 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
356a0 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
356b0 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
356c0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
356d0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
356e0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
356f0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
35700 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
35710 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
35720 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
35730 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54  me as INTEGER->T
35740 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
35750 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e   FLOAT   <td> IN
35760 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
35770 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
35780 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
35790 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
357a0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
357b0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
357c0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
357d0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
357e0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43   BLOB    <td> [C
357f0 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20  AST] to BLOB.** 
35800 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
35810 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
35820 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
35830 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
35840 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
35850 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
35860 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a   [CAST] to REAL.
35870 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
35880 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  T    <td>   BLOB
35890 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e      <td> No chan
358a0 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ge.** <tr><td>  
358b0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54  BLOB    <td> INT
358c0 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
358d0 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
358e0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
358f0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
35900 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
35910 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64   REAL.** <tr><td
35920 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
35930 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
35940 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
35950 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
35960 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
35970 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
35980 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
35990 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
359a0 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
359b0 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
359c0 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
359d0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
359e0 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
359f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
35a00 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
35a10 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
35a20 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
35a30 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
35a40 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
35a50 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
35a60 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
35a70 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
35a80 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
35a90 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
35aa0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
35ab0 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
35ac0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
35ad0 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
35ae0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35af0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
35b00 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
35b10 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
35b20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
35b30 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
35b40 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
35b50 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
35b60 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
35b70 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
35b80 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
35b90 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
35ba0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
35bb0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
35bc0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
35bd0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
35be0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
35bf0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
35c00 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
35c10 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
35c20 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
35c30 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
35c40 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
35c50 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
35c60 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
35c70 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
35c80 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
35c90 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
35ca0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f   </ul>.**.** ^Co
35cb0 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
35cc0 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
35cd0 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
35ce0 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
35cf0 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
35d00 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
35d10 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
35d20 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
35d30 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
35d40 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
35d50 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
35d60 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20  references will 
35d70 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
35d80 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
35d90 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
35da0 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
35db0 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
35dc0 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
35dd0 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
35de0 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
35df0 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
35e00 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
35e10 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
35e20 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
35e30 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  est policy is to
35e40 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
35e50 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
35e60 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
35e70 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
35e80 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
35e90 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
35ea0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
35eb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35ec0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
35ed0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
35ee0 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
35ef0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
35f00 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
35f10 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
35f20 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
35f30 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
35f40 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
35f50 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
35f60 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
35f70 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
35f80 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
35f90 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
35fa0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
35fb0 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
35fc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
35fd0 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
35fe0 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
35ff0 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
36000 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
36010 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
36020 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
36030 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
36040 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
36050 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
36060 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
36070 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
36080 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
36090 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
360a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
360b0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
360c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
360d0 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
360e0 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
360f0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
36100 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
36110 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
36120 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
36130 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tes()..**.** ^Th
36140 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
36150 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
36160 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
36170 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
36180 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
36190 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
361a0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
361b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
361c0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
361d0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
361e0 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d   called.  ^The m
361f0 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
36200 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
36210 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
36220 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
36230 61 6c 6c 79 2e 20 20 44 6f 20 6e 6f 74 20 70 61  ally.  Do not pa
36240 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20  ss the pointers 
36250 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
36260 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
36270 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
36280 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
36290 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20  ], etc. into.** 
362a0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
362b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d  ..**.** ^(If a m
362c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
362d0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
362e0 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74  ring the evaluat
362f0 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ion of any.** of
36300 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
36310 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65   a default value
36320 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
36330 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
36340 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68  .** is either th
36350 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65  e integer 0, the
36360 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
36370 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61  number 0.0, or a
36380 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
36390 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61  .  Subsequent ca
363a0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
363b0 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20  errcode()] will 
363c0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
363d0 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63  E_NOMEM].)^.*/.c
363e0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
363f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73  e3_column_blob(s
36400 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
36410 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20  t iCol);.double 
36420 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
36430 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
36440 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
36450 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
36460 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
36470 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
36480 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
36490 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
364a0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
364b0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
364c0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
364d0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
364e0 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
364f0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
36500 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
36510 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
36520 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
36530 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
36540 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
36550 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
36560 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
36570 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
36580 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
36590 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
365a0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
365b0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
365c0 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
365d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
365e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
365f0 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
36600 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
36610 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ol);../*.** CAPI
36620 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20  3REF: Destroy A 
36630 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
36640 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53  nt Object.** DES
36650 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
36660 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
36670 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
36680 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
36690 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
366a0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
366b0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
366c0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
366d0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68  evaluation of th
366e0 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f  e statement enco
366f0 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72  untered no error
36700 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73  s.** or if the s
36710 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65  tatement is neve
36720 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64  r been evaluated
36730 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66  , then sqlite3_f
36740 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e  inalize() return
36750 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20  s.** SQLITE_OK. 
36760 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
36770 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
36780 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66  of statement S f
36790 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73  ailed, then.** s
367a0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
367b0 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61  S) returns the a
367c0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
367d0 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  r code] or.** [e
367e0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
367f0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
36800 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
36810 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  (S) routine can 
36820 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
36830 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a   point during.**
36840 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20   the life cycle 
36850 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
36860 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65  tement] S:.** be
36870 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53  fore statement S
36880 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74   is ever evaluat
36890 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65  ed, after.** one
368a0 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74   or more calls t
368b0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
368c0 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e  ()], or after an
368d0 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71  y call.** to [sq
368e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
368f0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
36900 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73  her or not the s
36910 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20  tatement has.** 
36920 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
36930 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f  ion..**.** ^Invo
36940 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e  king sqlite3_fin
36950 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c  alize() on a NUL
36960 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68  L pointer is a h
36970 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
36980 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
36990 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69  tion must finali
369a0 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72  ze every [prepar
369b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
369c0 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a   order to avoid.
369d0 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b  ** resource leak
369e0 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65  s.  It is a grie
369f0 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74  vous error for t
36a00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
36a10 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20  o try to use.** 
36a20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
36a30 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
36a40 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
36a50 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20  .  Any use of a 
36a60 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
36a70 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
36a80 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
36a90 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20  d can result in 
36aa0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a  undefined and.**
36ab0 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
36ac0 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65  avior such as se
36ad0 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70  gfaults and heap
36ae0 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
36af0 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
36b00 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
36b10 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
36b20 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
36b30 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
36b40 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
36b50 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
36b60 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  _stmt.**.** The 
36b70 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
36b80 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
36b90 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
36ba0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36bb0 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
36bc0 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
36bd0 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
36be0 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
36bf0 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61  .** ^Any SQL sta
36c00 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
36c10 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
36c20 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
36c30 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
36c40 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
36c50 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
36c60 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
36c70 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
36c80 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
36c90 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
36ca0 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
36cb0 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ngs..**.** ^The 
36cc0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
36cd0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
36ce0 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
36cf0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
36d00 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65  * back to the be
36d10 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
36d20 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  rogram..**.** ^I
36d30 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
36d40 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
36d50 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
36d60 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
36d70 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65   statement] S re
36d80 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
36d90 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OW] or [SQLITE_D
36da0 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b  ONE],.** or if [
36db0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
36dc0 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
36dd0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
36de0 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c   S,.** then [sql
36df0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
36e00 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
36e10 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  K]..**.** ^If th
36e20 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
36e30 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
36e40 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
36e50 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
36e60 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
36e70 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
36e80 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  en.** [sqlite3_r
36e90 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
36ea0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
36eb0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
36ec0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
36ed0 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
36ee0 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63  rface does not c
36ef0 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73  hange the values
36f00 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69  .** of any [sqli
36f10 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
36f20 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b  ndings] on the [
36f30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
36f40 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nt] S..*/.int sq
36f50 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69  lite3_reset(sqli
36f60 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
36f70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36f80 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64  F: Create Or Red
36f90 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69  efine SQL Functi
36fa0 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
36fb0 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   {function creat
36fc0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a  ion routines}.**
36fd0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
36fe0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
36ff0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a  SQL function}.**
37000 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
37010 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
37020 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  SQL functions}.*
37030 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
37040 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  3.**.** ^These f
37050 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63  unctions (collec
37060 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  tively known as 
37070 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  "function creati
37080 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a  on routines").**
37090 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
370a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
370b0 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20  r aggregates or 
370c0 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20  to redefine the 
370d0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65  behavior.** of e
370e0 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
370f0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
37100 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64  tes.  The only d
37110 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65  ifferences betwe
37120 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74  en.** these rout
37130 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78  ines are the tex
37140 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63  t encoding expec
37150 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73  ted for.** the s
37160 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
37170 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  (the name of the
37180 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20   function being 
37190 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20  created).** and 
371a0 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20  the presence or 
371b0 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73  absence of a des
371c0 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
371d0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c   for.** the appl
371e0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
371f0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
37200 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
37210 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73   is the [databas
37220 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
37230 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a   which the SQL.*
37240 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f  * function is to
37250 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20   be added.  ^If 
37260 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
37270 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
37280 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
37290 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70  nnection then 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 20  d SQL functions 
372c0 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a  must be added.**
372d0 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
372e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70  e connection sep
372f0 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  arately..**.** ^
37300 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
37310 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
37320 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
37330 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74  tion to be creat
37340 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e  ed or.** redefin
37350 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68  ed.  ^The length
37360 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20   of the name is 
37370 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62  limited to 255 b
37380 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a  ytes in a UTF-8.
37390 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ** representatio
373a0 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20  n, exclusive of 
373b0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
373c0 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74  tor.  ^Note that
373d0 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e   the name.** len
373e0 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20  gth limit is in 
373f0 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74  UTF-8 bytes, not
37400 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20   characters nor 
37410 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a  UTF-16 bytes.  .
37420 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20  ** ^Any attempt 
37430 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63  to create a func
37440 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67  tion with a long
37450 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  er name.** will 
37460 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54  result in [SQLIT
37470 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20  E_MISUSE] being 
37480 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
37490 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
374a0 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69  eter (nArg).** i
374b0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
374c0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74  arguments that t
374d0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
374e0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
374f0 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20  takes. ^If this 
37500 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c  parameter is -1,
37510 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75   then the SQL fu
37520 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
37530 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20  regate may take 
37540 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  any number of ar
37550 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20  guments between 
37560 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a  0 and the limit.
37570 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74  ** set by [sqlit
37580 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
37590 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
375a0 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20  _ARG]).  If the 
375b0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
375c0 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  er is less than 
375d0 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  -1 or greater th
375e0 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20  an 127 then the 
375f0 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75  behavior is.** u
37600 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
37610 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
37620 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c  meter, eTextRep,
37630 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a   specifies what.
37640 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
37650 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  | text encoding]
37660 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69   this SQL functi
37670 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a  on prefers for.*
37680 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73  * its parameters
37690 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
376a0 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68  on should set th
376b0 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  is parameter to.
376c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ** [SQLITE_UTF16
376d0 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74  LE] if the funct
376e0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
376f0 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b  on invokes .** [
37700 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
37710 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20  xt16le()] on an 
37720 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54  input, or [SQLIT
37730 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74 68  E_UTF16BE] if th
37740 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
37750 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c  ion invokes [sql
37760 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
37770 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70  6be()] on an inp
37780 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  ut, or.** [SQLIT
37790 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c  E_UTF16] if [sql
377a0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
377b0 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72  6()] is used, or
377c0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a   [SQLITE_UTF8].*
377d0 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54  * otherwise.  ^T
377e0 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
377f0 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69  tion may be regi
37800 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20  stered multiple 
37810 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64  times using.** d
37820 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 72 72  ifferent preferr
37830 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
37840 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  s, with differen
37850 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
37860 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e  s for.** each en
37870 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e  coding..** ^When
37880 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
37890 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
378a0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61   same function a
378b0 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51  re available, SQ
378c0 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63  Lite.** will pic
378d0 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69  k the one that i
378e0 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73  nvolves the leas
378f0 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
37900 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
37910 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
37920 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74  arameter may opt
37930 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20  ionally be ORed 
37940 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54  with [SQLITE_DET
37950 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74  ERMINISTIC].** t
37960 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68  o signal that th
37970 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  e function will 
37980 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68  always return th
37990 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69  e same result gi
379a0 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ven.** the same 
379b0 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61 20  inputs within a 
379c0 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
379d0 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20  ment.  Most SQL 
379e0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a  functions are.**
379f0 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20   deterministic. 
37a00 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72   The built-in [r
37a10 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e  andom()] SQL fun
37a20 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d  ction is an exam
37a30 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63  ple of a.** func
37a40 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74  tion that is not
37a50 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20   deterministic. 
37a60 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65 72   The SQLite quer
37a70 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c  y planner is abl
37a80 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20  e to.** perform 
37a90 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d  additional optim
37aa0 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65  izations on dete
37ab0 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69  rministic functi
37ac0 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f  ons, so use.** o
37ad0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45  f the [SQLITE_DE
37ae0 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61  TERMINISTIC] fla
37af0 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  g is recommended
37b00 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e   where possible.
37b10 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66  .**.** ^(The fif
37b20 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
37b30 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69  an arbitrary poi
37b40 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65  nter.  The imple
37b50 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
37b60 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  .** function can
37b70 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20   gain access to 
37b80 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69  this pointer usi
37b90 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ng [sqlite3_user
37ba0 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a  _data()].)^.**.*
37bb0 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65  * ^The sixth, se
37bc0 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68  venth and eighth
37bd0 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75   parameters, xFu
37be0 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46  nc, xStep and xF
37bf0 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69  inal, are.** poi
37c00 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75  nters to C-langu
37c10 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  age functions th
37c20 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
37c30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
37c40 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e  .** aggregate. ^
37c50 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  A scalar SQL fun
37c60 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
37c70 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
37c80 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a   of the xFunc.**
37c90 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20   callback only; 
37ca0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75  NULL pointers mu
37cb0 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
37cc0 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46  the xStep and xF
37cd0 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65  inal.** paramete
37ce0 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74  rs. ^An aggregat
37cf0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
37d00 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
37d10 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74  mentation of xSt
37d20 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c  ep.** and xFinal
37d30 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   and NULL pointe
37d40 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  r must be passed
37d50 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20   for xFunc. ^To 
37d60 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69  delete an existi
37d70 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  ng.** SQL functi
37d80 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
37d90 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74   pass NULL point
37da0 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ers for all thre
37db0 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61  e function.** ca
37dc0 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e  llbacks..**.** ^
37dd0 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61  (If the ninth pa
37de0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
37df0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
37e00 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e  on_v2() is not N
37e10 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  ULL,.** then it 
37e20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f  is destructor fo
37e30 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
37e40 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20  n data pointer. 
37e50 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74  .** The destruct
37e60 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  or is invoked wh
37e70 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
37e80 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68  is deleted, eith
37e90 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f  er by being.** o
37ea0 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65  verloaded or whe
37eb0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
37ec0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
37ed0 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74  .)^.** ^The dest
37ee0 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69  ructor is also i
37ef0 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61  nvoked if the ca
37f00 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
37f10 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
37f20 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20  _v2() fails..** 
37f30 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75  ^When the destru
37f40 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ctor callback of
37f50 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d   the tenth param
37f60 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c  eter is invoked,
37f70 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64   it.** is passed
37f80 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
37f90 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f  nt which is a co
37fa0 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  py of the applic
37fb0 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70  ation data .** p
37fc0 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73  ointer which was
37fd0 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d   the fifth param
37fe0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
37ff0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
38000 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  v2()..**.** ^It 
38010 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
38020 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c  register multipl
38030 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
38040 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
38050 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20   functions with 
38060 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
38070 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69  t with either di
38080 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20  ffering numbers 
38090 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  of.** arguments 
380a0 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65  or differing pre
380b0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
380c0 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20  dings.  ^SQLite 
380d0 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20  will use.** the 
380e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74  implementation t
380f0 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  hat most closely
38100 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
38110 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
38120 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
38130 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74   used.  ^A funct
38140 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
38150 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65  on with a non-ne
38160 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70  gative.** nArg p
38170 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65  arameter is a be
38180 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  tter match than 
38190 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  a function imple
381a0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a  mentation with.*
381b0 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72  * a negative nAr
381c0 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  g.  ^A function 
381d0 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72  where the prefer
381e0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
381f0 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65  g.** matches the
38200 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69   database encodi
38210 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a  ng is a better.*
38220 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  * match than a f
38230 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
38240 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  e encoding is di
38250 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41  fferent.  .** ^A
38260 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
38270 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
38280 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65  ference is betwe
38290 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55  en UTF16le and U
382a0 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63  TF16be.** is a c
382b0 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e  loser match than
382c0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
382d0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
382e0 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20  ifference is.** 
382f0 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64  between UTF8 and
38300 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42   UTF16..**.** ^B
38310 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
38320 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61  s may be overloa
38330 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69  ded by new appli
38340 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
38350 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  unctions..**.** 
38360 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ^An application-
38370 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
38380 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
38390 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53   call other.** S
383a0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
383b0 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68  .  However, such
383c0 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a   calls must not.
383d0 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ** close the dat
383e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
383f0 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72   nor finalize or
38400 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
38410 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
38420 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75   in which the fu
38430 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
38440 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  g..*/.int sqlite
38450 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
38460 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
38470 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
38480 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
38490 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
384a0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
384b0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
384c0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
384d0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
384e0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
384f0 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
38500 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
38510 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
38520 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
38530 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
38540 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
38550 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
38560 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71  function16(.  sq
38570 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
38580 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69  st void *zFuncti
38590 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
385a0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
385b0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
385c0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
385d0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
385e0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
385f0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
38600 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
38610 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
38620 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
38630 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
38640 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
38650 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
38660 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
38670 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  n_v2(.  sqlite3 
38680 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
38690 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
386a0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
386b0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
386c0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
386d0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
386e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
386f0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
38700 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
38710 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
38720 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
38730 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
38740 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
38750 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20  e3_context*),.  
38760 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
38770 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
38780 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text